[PYTHON] sphinx-apidoc setuptools integration

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.

Introduction

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.

Method

Preparation

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/

Add code for build

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/*

Run

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.

reference

• Stackoverflow, "Autogenerate documentation for Python project using setuptools"