TutorialΒΆ
The first thing you can do is it to create a new sphinx template project for your organization in GitHub (just like this one).
Taking this project as the baseline,
first of all you create a requirements-docs.txt
and
add it to the MANIFEST.in
file.
The requirements-docs
file should contain all the dependencies
you’ll need to build the Sphinx documentation for your project.
For example:
recommonmark==0.4.0
semantic_version==2.6.0
Sphinx==1.4.8
sphinx_rtd_theme==0.1.9
After this you can setup the docs
virtualenv in tox
.
For example:
[testenv:docs]
usedevelop = False
changedir = docs
deps =
-rrequirements.txt
-rrequirements-docs.txt
commands =
steenzout-sphinx-generate organization organization.sphinx .
make dummy
make apidoc
make coverage
make changes
make html
whitelist_externals =
/usr/bin/make
Before you continue, you’ll need to create a metadata module.
For example:
__author__ = u'Myself'
__author_email__ = u'email@example.com'
__classifiers__ = [
'Development Status :: 5 - Production/Stable',
'Intended Audience :: Developers',
'License :: OSI Approved :: Apache Software License',
'Operating System :: OS Independent',
'Programming Language :: Python',
'Programming Language :: Python :: 2',
'Programming Language :: Python :: 2.7',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.5',
'Programming Language :: Python :: Implementation :: CPython',
'Topic :: Documentation',
'Topic :: Documentation :: Sphinx',
'Topic :: Software Development :: Documentation'
]
__copyright__ = u'2016, %s' % __author__
__description__ = u'Sphinx configuration for YOUR GitHub organization.'
__maintainer__ = u'Myself'
__maintainer_email__ = u'email@example.com'
__url__ = u'https://github.com/organization/python-sphinx/'
__version__ = u'0.0.1'
This metadata module must be placed
under organization/sphinx/metadata.py
directory or
else this library won’t find it.
The next step is to create a templates
directory under organization/sphinx
.
In this directory you should place the conf.py.j2
and Makefile.j2
templates you need.
Check this project template files for an example.
After you complete all of these tasks you can now generate your documentation using
$ tox -e docs
After you complete these steps and you are happy with the results
you can use your new organization.sphinx
templates in any of your projects.
To achieves this you setup your requirements-docs.txt
by addding your organization.sphinx
package.
-e git+git@github.com:organization/python-sphinx.git@master#egg=organization-sphinx-master
The tox.ini
file for the project will only change the package being documented.
[testenv:docs]
usedevelop = False
changedir = docs
deps =
-rrequirements.txt
-rrequirements-docs.txt
commands =
steenzout-sphinx-generate organization organization.project .
make dummy
make apidoc
make coverage
make changes
make html
whitelist_externals =
/usr/bin/make
You also need to add the project metadata into the
organization/project/metadata.py
file.
In the end you can generate all the documentation
with the tox -e docs
command.
The End