This section provides an overview of what python-sphinx is, and why a developer might want to use it.
It should also mention any large subjects within python-sphinx, and link out to the related topics. Since the Documentation for python-sphinx is new, you may need to create initial versions of those related topics.
Installation or Setup
pip install Sphinx
or you can also install using easy_install
easy_install -U sphinx
Then you can check that it has been correctly installed by executing the following command:
> sphinx-quickstart --version Sphinx v1.4.1
Before proceeding ahead you need to follow certain code style for python PEP 8. If you have followed PEP 8 guideline then you can define document structure in sphinx and start building your documentation.
To get started go to root of project directory and run :
You will get options to create documentation for your project. For default setup follow below commands:
Prompt Choice > Root path for the documentation [.]: <ENTER> > Separate source and build directories (y/N) [n]: y > Name prefix for templates and static dir [_]: <ENTER> > Project name: an_example_pypi_project > Author name(s): Andrew Carter > Project version: 0.0.1 > Project release [0.0.1]: <ENTER> > Source file suffix [.rst]: <ENTER> > Name of your master document (without suffix) [index]: <ENTER> > autodoc: automatically insert docstrings from modules (y/N) [n]: y > doctest: automatically test code snippets in doctest blocks (y/N) [n]: n > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y > todo: write “todo” entries that can be shown or hidden on build (y/N) [n]: n > coverage: checks for documentation coverage (y/N) [n]: n > pngmath: include math, rendered as PNG images (y/N) [n]: n > jsmath: include math, rendered in the browser by JSMath (y/N) [n]: n > ifconfig: conditional inclusion of content based on config values (y/N) [n]: y > Create Makefile? (Y/n) [y]: n > Create Windows command file? (Y/n) [y]: n
Upon successful execution you may discover config.py file in your doc/source directory of your project. This file has control to basic structure of how your document will generate when you run build command as below
$ sphinx-build -b html sourcedir builddir
Detailed instructions are avilable at : https://pythonhosted.org/an_example_pypi_project/sphinx.html