Tasks details¶
Please refer to the documentation on Using invoke-sphinx for a discussion on invoke
vs vinvoke
vs pipenv run invoke
.
Clean¶
docs.clean¶
$ invoke docs.clean
This will clean the docs/_build directory to ensure fresh documentation (especially in case of file removal).
Implementation note: docs.clean
is the equivalent of the Sphinx command:
$ make -C docs clean
Open¶
docs.open¶
$ invoke docs.open [--local]
This will open your browser at your documentation url, on the remote server. If --local
or -l
flag is passed, the local documentation is opened instead.
This does not (re)build your documentation, so if the --local
flag is used, you need to build your documentation locally first.
Implementation note: docs.open
delegates to xdp-open
command.
Test¶
docs.test¶
$ invoke docs.test
This will test the links in your documentation, and report potential issues. This is usefull to ensure your documentation is coherent, both for internal and external links.
Implementation note: docs.test
is the equivalent of the Sphinx command:
$ make -C docs linkcheck
Build¶
docs.build¶
$ invoke docs.build
This will generate the HTML documentation in the docs/_build/html directory. You can visualize it by browsing your navigator to this directory.
It will always call the docs.clean task first.
Implementation note: docs.build
is the equivalent of the Sphinx command:
$ make -C docs html
docs.build-versions¶
$ invoke docs.build-versions
This will generate the HTML documentation in the docs/_build/html directory, for all your project versions. You can visualize it by browsing your navigator to this directory.
Note
In this case, the documentation generation is done through what is available in the git repository. Local changes are not taken into account.
It will always call the docs.clean task first.
Implementation note: docs.build-versions
is the equivalent of the Sphinx command:
$ sphinx-versioning build docs docs/_build/html
where build
is the command, docs
the directory containing your documentation, and docs/_build/html
the target directory.
docs.build-pdf¶
$ invoke docs.build-pdf
This will generate the PDF documentation in the docs/_build/latex directory. You can visualize it by browsing your file explorer to this directory.
It will always call the docs.clean task first.
Note
You might need to install latex on your local computer first. See Install Latex for more information.
Implementation note: docs.build-pdf
is the equivalent of the Sphinx command:
$ make -C docs latexpdf
Live Build¶
docs.live¶
$ invoke docs.live
This will scan your documentation and build it everytime you change a file. It will also open a brower poiting to your local documentation. It includes a live-reload server, which reloads your current page if it changes.
This is particularly usefull if you are currently updating your documentation, to see changes in real-time.
Note
This is the default task of the docs module, meaning you can simply use invoke docs
to call this task.
Implementation note: docs.live
is the equivalent of the sphinx-autobuild command:
$ sphinx-autobuild -B --delay 1 -b html docs docs/_build/html
… with some files being ignored as well.
Publish¶
Documentation is published on the remote server defined in the configuration file invoke.yml
.
docs.publish¶
$ invoke docs.publish
This will rsync the docs/_build/html directory to the remote server.
It will always call the docs.build task first.
Implementation note: docs.publish
is the equivalent of the command:
$ rsync -r -P -e ssh docs/_build/html/ ${remote_doc_server_username}@${remote_doc_server}:${remote_doc_server_path_prefix}/${publishing_dir}/
docs.publish-versions¶
$ invoke docs.publish-versions
This will rsync the docs/_build/html directory to the remote server. It is the same command as docs.publish, the difference being the generation task called first.
It will always call the docs.build-versions task first.