search

davidrpugh / penn-world-tables

Python module for generating the Penn World Tables data set.
5 stars 5 forks source link

Sphinx auto-docs #1

Open davidrpugh opened 10 years ago

davidrpugh commented 10 years ago

Set up auto-generated documentation using Sphinx.

davidrpugh commented 10 years ago

Consider using readthedocs to host project documentation generated by Sphinx.

davidrpugh commented 10 years ago

Project documentation now being hosted at http://pypwt.readthedocs.org/. I also was able to add a commit hook so that the documentation will get rebuilt whenever I make changes.

Still need to figure out how to use Sphinx to auto-generate the docs using the docstrings before I can close this issue.

davidrpugh commented 10 years ago

Progress has kind of been made. Apparently I needed to run:

$ sphinx-apidoc -o docs/source pypwt

from within the pyPWT directory in order to generate the documentation files prior to trying to build docs. Now docs build fine locally, but when I check the documentation on http://pypwt.readthedocs.org/ it does not show the docstrings for any of the functions in the package.

davidrpugh commented 10 years ago

Technically docs build with warnings:

davids-mbp:docs drpugh$ make html
sphinx-build -b html -d build/doctrees   source build/html
Making output directory...
Running Sphinx v1.2.2
loading pickled environment... not yet created
building [html]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
reading sources... [100%] pypwt.test                                            
/Users/drpugh/Research/penn-world-tables/pyPWT/pypwt/pwt.py:docstring of pypwt.pwt.load_pwt_data:4: SEVERE: Unexpected section title.

Parameters
----------
/Users/drpugh/Research/penn-world-tables/pyPWT/pypwt/pwt.py:docstring of pypwt.pwt.load_pwt_data:11: SEVERE: Unexpected section title.

Returns
-------
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/drpugh/Research/penn-world-tables/pyPWT/docs/source/modules.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] pypwt.test                                             
writing additional files... (2 module code pages) _modules/index genindex py-modindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded, 3 warnings.

Build finished. The HTML pages are in build/html.

Perhaps this is because I am using NumPy formatted docstrings within using the appropriate Sphinx extensions?