Skip to content

Commit

Permalink
Merge pull request #16 from dssg/docs
Browse files Browse the repository at this point in the history
basic documentation

**Changes**

* rounded out library docstrings, such that the heart of the (API) documentation is there
* integrated with Sphinx (and autodoc)
  * such that standard documentation can be generated from docstrings, (tho HTML currently unused)
  * submitted patches to extension [sphinx-contrib.restbuilder](sphinx-contrib/restbuilder#8), such that Sphinx can also build RST docs – (it's a little surprising that Sphinx can't on its own or otherwise its build process can't be intercepted to retrieve RST formatted output before it's parsed into an abstract tree, considering its input is RST, albeit Sphinx- and autodoc-extended RST; but, nonetheless, this appeared to be the easiest way forward ... though markdown is another obvious target, it doesn't cleanly support all the directives that you get from RST ... and Github won't render README.html).
  * scripted a development command to generate HTML docs and README.rst

In the end, I don't love [how the auto-generated README.rst looks](https://github.com/dssg/ohio/tree/docs), at least not as Github renders it; but, for something like this, I think it's fine, and keeps API documentation in the code.

A discussion of [benchmarking the Pandas extension](#11) is included in `doc/index.rst` (and from there included in built documentation).

resolves #1
  • Loading branch information
jesteria authored Apr 11, 2019
2 parents 0a8e322 + fa5230b commit 819808a
Show file tree
Hide file tree
Showing 22 changed files with 3,966 additions and 44 deletions.
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ instance/
.scrapy

# Sphinx documentation
docs/_build/
doc/_build/

# PyBuilder
target/
Expand Down
4 changes: 0 additions & 4 deletions README.md

This file was deleted.

Loading

0 comments on commit 819808a

Please sign in to comment.