Documentation
Access online documentation
The latest version of Crappy’s code can be found on GitHub, and the latest version of Crappy’s documentation can be found on ReadTheDocs.
An easy way to access the online documentation is to run in a Python console :
>>> import crappy
>>> crappy.doc()
This will open the documentation in a new tab or window of your default browser, hard to be quicker than that ! Of course you still need an internet connection.
Build local documentation
Required packages
All the documentation is actually contained in Crappy’s .py
files in the
form of docstrings and in the .rst
files. It is thus possible to build the
documentation locally as soon as Crappy is installed.
To build it yourself, first install sphinx
. This can be done easily using
pip
, more detail here. You will also
need sphinx_rtd_theme
, which is distributed on PyPI and should also be installed via
pip
.
Getting the doc files
Then, you need to get the .rst
files and the Makefile. There are several
options :
Regardless of how Crappy was installed, it is possible to download the Makefile and
.rst
files from the Github repository.If you installed Crappy using
git
andsetup
, then the Makefile and.rst
files are located in the/<install_path>/crappy/docs/
folder (orC:\<install_path>\crappy\docs\
on Windows).If you installed Crappy in a virtualenv, the Makefile and
.rst
files are located in your virtualenv folder in/crappy/docs/
.If you installed Crappy via
pip
on your system, there’s no guarantee on where the Makefile and.rst
files have been copied bypip
. Downloading them is probably the easiest way to go. It is nevertheless for sure that they’re somewhere in a/crappy/docs/
folder (\crappy\docs\
on Windows). From our own experience, this folder may be located :In
/home/<username>/.local/
in Linux (tested on Ubuntu 20.04).In
C:\Users\<username>\AppData\Local\Programs\Python\Pythonxy\
in Windows, x.y being the installed Python version (tested on Windows 10).In
/Library/Frameworks/Python.framework/Versions/Current/
in macOS (tested on mac Sierra).
Building the documentation
Once you located or downloaded the Makefile and .rst
files, simply open a
terminal in the directory where Makefile is. Assuming that the folder containing
the .rst
files is located in the same directory and called source
,
simply run :
sphinx-build -b html source build
This will create a new directory build
, containing the .html
documentation files. These files can be opened using your regular web browser.
Note that the building process can be tuned in several ways (format, folders path and names, etc.), see Sphinx documentation for details.
For Linux users, running :
make html
Is a simpler way of calling the building command outputting .html
files with
the default arguments.