Skip to content
This repository has been archived by the owner on Jan 15, 2019. It is now read-only.

Commit

Permalink
Workaround for RTD auto-generated docs
Browse files Browse the repository at this point in the history 
I realized I had never actually tested the work around listed here: readthedocs/readthedocs.org#1139 I'm going to try that and see how it goes...
  • Loading branch information
@brahmlower
brahmlower committed Sep 5, 2016
1 parent de976a3 commit 481b85e
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 0 deletions.
8 changes: 8 additions & 0 deletions docs/readme.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Documentation setup

## Dependencies
Sphinx documentation generation is done via Make. You will need sphinx and sphinx_rtd_theme installed:
pip install sphinx sphinx_rtd_theme

## Build Process
make html
17 changes: 17 additions & 0 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -287,3 +287,20 @@
#texinfo_no_detailmenu = False

autodoc_member_order = 'bysource'


def run_apidoc(_):
modules = ['cssefclient',
'cssefserver',
'cssefserver.account']
for module in modules:
cur_dir = os.path.abspath(os.path.dirname(__file__))
output_path = os.path.join(cur_dir, module, 'doc')
cmd_path = 'sphinx-apidoc'
if hasattr(sys, 'real_prefix'): # Check to see if we are in a virtualenv
# If we are, assemble the path manually
cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'sphinx-apidoc'))
subprocess.check_call([cmd_path, '-e', '-o', output_path, module, '--force'])

def setup(app):
app.connect('builder-inited', run_apidoc)

2 comments on commit 481b85e

@jindrahelcl
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, did that work? :-)

@brahmlower
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The short answer is: kind of.
This change alone wasn't enough, but it put me on the right path to finding a working solution. The following is a (hopefully helpful) recap of what I ended up doing:

I found that several projects have defined an "ext" module that they import in the sphinx conf.py file. For example, after implementing the "ext" module, my folder structure looks like:

user@debian:~/development/cssef/docs$ tree
.
├── ext
│   ├── apidoc.py
│   └── __init__.py
├── requirements.rtd.txt
└── source
    ├── conf.py

and the extensions list looks like (the two important imports being sphinx.ext.autodoc and ext.apidoc):

# in .../docs/source/conf.py

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'ext.apidoc'
]

For this to work, you have to add the modules to the module path, which is actually explained in comments just above the "General Configuration" section of an auto-generated sphinx conf.py file. In my case I've added paths to the two modules I'm testing, as well as the path to the "ext" module that actually executes autodoc:

# in .../docs/source/conf.py

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../../CssefServer'))
sys.path.insert(0, os.path.abspath('../../CssefClient'))
# Inspired by an openstack config I found
# https://github.com/openstack/deb-python-pycadf/blob/master/doc/source/conf.py
sys.path.insert(0, os.path.abspath('..'))

The contents of .../docs/ext/apidoc.py work very similarly to the changes I made in this commit. There's a great example in the openstack deb-python-pycadf repo, which I've tweaked to fit my particular situation. My version just takes into account the two packages I'm testing, and excludes 'setup.py' and 'tests' which were causing a bunch of apidoc errors.

I hope this was helpful for you, and possibly others in the future. If you have any questions, let me know. :)

Please sign in to comment.