I have [posted] a better practice than below (http://qiita.com/koreyou/items/00f5820591ec9196ef07). I think the practice in this post is also valid depending on the conditions, so I will leave it for now.
sphinx-apidoc is a powerful API documentation creation automation tool. There is a sphinx integration tool in setuptools, but in order to use sphinx-apidoc, you need to run sphinx-apidoc once with CLI and then build sphinx with setuptools, etc. Automation is not good //github.com/sphinx-doc/sphinx/issues/1135). This post describes how to run both sphinx-apidoc and sphinx with one command.
By the way, I'm not involved in OSS development, so I'm not sure if the following is a good practice.
Install Sphinx and create a directory of documents.
$ pip install sphinx
$ sphinx-quickstart
Follow the quick start to fill in the questions as appropriate. Below is a collection of only the questions that need to be answered to take this approach.
Welcome to the Sphinx 1.6.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]: doc
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
...
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
Then, a doc /
directory with the following structure will be created under the directory.
.
├── doc/
│ ├── build/
│ └── source/
│ ├── _build/
│ ├── conf.py
│ ├── index.rst
│ ├── _static/
│ └── _templates/
├── README.md
├── setup.cfg
├── setup.py
├── test/
├── my_project/
Write setup.py as follows. When using only sphinx, just write setup (cmd class = {'build_sphinx': BuildDoc}, ...)
, but this time inherited that BuildDoc
and added ʻapidoc` as preprocessing. Define a new command.
setup.py
import os
from setuptools import setup
from setuptools.extension import Extension
import sphinx.apidoc
from sphinx.setup_command import BuildDoc
class BuildDocApiDoc(BuildDoc, object):
# inherit from object to enable 'super'
user_options = []
description = 'sphinx'
def run(self):
# metadata contains information supplied in setup()
metadata = self.distribution.metadata
# package_dir may be None, in that case use the current directory.
src_dir = (self.distribution.package_dir or {'': ''})['']
src_dir = os.path.join(os.getcwd(), src_dir)
# Run sphinx by calling the main method, '--full' also adds a conf.py
sphinx.apidoc.main(
['', '-f', '-H', metadata.name, '-A', metadata.author,
'-V', metadata.version, '-R', metadata.version, '-T',
'-o', os.path.join('doc', 'source', 'modules'), src_dir])
super(BuildDocApiDoc, self).run()
name = 'my_project'
version = '0.1'
release = '0.1.0'
setup(
name=name,
author='koreyou',
version=version,
packages=['my_project', ],
license='Creative Commons BY',
cmdclass = {'build_sphinx': BuildDocApiDoc},
command_options={
'build_sphinx': {
'project': ('setup.py', name),
'version': ('setup.py', version),
'release': ('setup.py', release)}},
setup_requires = ['sphinx'],
)
In addition, rewrite some files.
setup.cfg
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
doc/source/conf.py
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))
doc/source/index.rst
.. toctree::
- :maxdepth: 2
- :caption: Contents:
+ :glob:
+ :caption: Modules
+ :maxdepth: 4
+ modules/*
python setup.up build_sphinx
After various information has been passed, if it finishes normally, API documentation should be created under doc / build / html / index.html
.
Also, regarding version control, doc / source / modules
is automatically generated, so enter only doc / source / conf.py
and doc / source / index.rst
, and add doc / build
. doc / source / module
is in .gitignore
.