Using invoke-sphinx¶
First, you need to comply with the Usage Requirements.
Install invoke-sphinx itself¶
To install invoke-sphinx itself, you can simply use pip or, preferably, use pipenv.
If you choose pipenv as your recommended installation tool, you might need to install it first using
$ pip install --user -U pipenv
Then , simply use the following command:
$ pipenv install invoke-sphinx
Integrate invoke-sphinx in your project¶
To benefit from the tasks defined in invoke-sphinx in your own project, you should create a tasks.py
file at the root of your project, containing (at least):
import invoke
from invoke import task, Collection
from invoke_sphinx import docs
ns = Collection(docs)
Note
Please refer to the original invoke documentation for more information about what can be achieved through this tool.
You also need to create an invoke.yml
file, at the root of your project, containing (at least):
---
#######################################
### Constants used to publish doc ###
#######################################
### remote doc server configuration
# server host or IP
remote_doc_server: '...'
# username used to push documentation on the remote server
remote_doc_server_username: '...'
# password for the username used to push documentation on the remote server
remote_doc_server_password: '...'
# directory prefix in which the documentation is pushed (for example /var/www)
remote_doc_server_path_prefix: '...'
# project specific directory in which the documentation is pushed.
# this path is appended to the path_prefix above to define the directory in which the documentation is pushed
# this path is also appended to the url used to expose your documentation (through the remote doc server)
publishing_dir: '...'
These constants are used by tasks in invoke-sphinx project to publish your documentation on the remote server.
Note
You need, of course, to set values appropriate to your context.
Use invoke-sphinx tasks¶
Now that everything is ready, you can use invoke --list
to see the list of tasks available.
Note
If you have installed invoke-sphinx with pipenv (which you should), you need to prefix your invoke
commands with pipenv run ...
or execute them in your virtualenv (see pipenv documentation for more information on this matter.
For example, to generate your documentaton locally, use invoke docs.build
. This will compile your *.rst files into an html site, browsable from the docs/_build/html directory. The sources rst files are expected to be available in the docs directory.
For a detailed explanation of each task, see Tasks details.
Note
The invoke-sphinx project is using itself to handle its own documentation. Thus, it can serve as an example of how to integrate it into your own project.
Tips¶
Tab completion¶
You can benefit from tab completion with invoke
commands.
To get it, you can add the following line in your ~/.bash_aliases
:
alias invoke-tab-completion="source <(invoke --print-completion-script bash)"
Then, simply execute invoke-tab-completion
from the directory containing your tasks.py
and start enjoying tab completion!
This will only impact your current shell. You need to do it each time you open a new shell. Also, when switching project, simply execute the command again to adapt the tab completion for your other commands.
If installed from pipenv, it is recommended to define the following aliases:
alias vinvoke="pipenv run invoke"
alias vinvoke-completion="source <(vinvoke --print-completion-script bash | sed -e 's/invoke/vinvoke/g')"
For the lazy ones¶
inv
is an alias for invoke
. You can use inv docs.build
instead of invoke docs.build
for example : 3 characters gained !!
Still, the pipenv run thing still applies, so you could actually use pipenv run inv
.