Skip to main content

Reference documentation generator for sphinx

Project description

.. image:: https://circleci.com/gh/novopl/sphinx-refdoc.svg?style=shield&circle-token=dc2b684d5decc1458c6c240fde9b4b548290c10c
:target: https://circleci.com/gh/novopl/sphinx-refdoc/tree/master

About
=====

**sphinx-refdoc** is a python reference documentation generator for Sphinx.


Installation
============

.. code-block:: shell

$ pip install sphinx-refdoc


Usage
=====

.. code-block:: shell

$ sphinx-refdoc <src_dir> <out_dir>

``sphinx-refdoc`` will parse you're source tree passed as the first parameter.
It will then generate a stub for sphinx reference documentation for that source.
It auto-generates all required files (one per module) and creates a navigation
based on the package structure of the source code.

It then saves it into the directory passed as the second argument. This will
usually be a subdirectory of the sphinx documentation directory. You can then
easily include the generated docs with you existing documentation by pointing
to the `<out_dir>/index.rst`. Lets say you have a following directory
structure::

docs/
├── ref/
└── index.rst

where ``docs/ref`` is the directory containing the generated reference docs
(2nd argument of ``sphinx-refdoc`` invocation) and index.rst is the
documentation main index file (conf.py points to it). Then if you want to
include the reference documentation, you just need to add ``ref/index`` to the
toctree. For example:

.. code-block:: rst

.. toctree::

my_topic_1
my_topic_2
docs/ref


Contributing
============

Setting up development repo
---------------------------

.. code-block:: shell

$ git clone git@github.com:novopl/sphinx-refdoc.git
$ cd sphinx-refdoc
$ virtualenv env
$ source ./env/bin/activate
$ ./devinit.sh


.. toctree::
:maxdepth: 3

docs/ref/index

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-refdoc-0.0.14.tar.gz (6.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page