Improving and Building the Documentation

PyInstaller ’s documentation is created using Sphinx . Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils .

The documentation is maintained in the Git repository along with the code and pushing to the develop branch will create a new version at https://pyinstaller.readthedocs.io/en/latest/ .

For small changes (like typos) you may just fork PyInstaller on Github, edit the documentation online and create a pull-request.

For anything else we ask you to clone the repository and verify your changes like this:

pip install sphinx sphinx_rtd_theme
cd doc
make html
xdg-open _build/html/index.html
								

Please watch out for any warning and error while building the documentation. In your browser check if the markup is

Prior to pushing your changes and creating the pull-request please run:

make clean html
								

to verify once again everything is fine. Thank you!

We may ask you to rework your changes or reword your commit messages. In this case, use git rebase -i and git push -f to update your pull-request. See Updating a Pull-Request 了解细节。

PyInstaller extensions

For the PyInstaller documentation there are roles available [*] in additon to the ones from Sphinx and docutils .

:commit:

Refer to a commit, creating a web-link to the online git repository. The commit-id will be shortened to 8 digits for readability. Example: :commit:`a1b2c3d4e5f6a7b8c9` will become a1b2c3d4 .

:issue:

Link to an issue or pull-request number at Github. Example: :issue:`123` will become #123 .

[*] Defined in doc/_extensions/pyi_sphinx_roles.py

reStructuredText Cheat-sheet

  • Combining markup and links:

    The easies way to install PyInstaller is using |pip|_::
    .. |pip| replace:: :command:`pip`
    .. _pip: https://pip.pypa.io/