Added tools for automated documentation with Sphinx and Numpydoc #88
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Using numpydoc allows aesthetically pleasing and easy to read documents to be created using Sphinx. You can see real examples of this with Numpy's own documentation (https://docs.scipy.org/doc/numpy-1.10.0/reference/generated/numpy.mean.html). This docs directory contains the basic file structure necessary for creating automated documentation based off NumPy styled Docstrings.
|
Thanks! I will try to get the docs hosted soon. |
|
No problem! Thanks for the merge! |
|
@nickstanisha I pushed the docs to the gh-pages branch. Any idea why some files are 404'ing despite being in the branch? http://tylertreat.github.io/BigQuery-Python/ |
|
@tylertreat I don't see any 404-ing casually browsing through the docs. Try adding a blank .nojekyll file at the top directory of your branch to prevent GitHub pages from processing the HTML with Jekyll. That should make everything behave like you'd expect. |
|
That did the trick, thanks! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I've added a docs directory containing the necessary scripts and tools to make some simple automated documentation using Sphinx. I've also changed the docstrings to use the Numpy style so that the automated documentation can be presented in the nice format provided by Numpydoc. In addition to the nice formatting, Sphinx also provides tools for searching and browsing the documenation.
Moving forward, you could decide to follow these directions and host your documentation on Github directly, which I've done here: https://nickstanisha.github.io/BigQuery-Python/ by creating a gh-pages branch of my fork.
The content of the documentation stayed the same, the only change was the formatting. Additionally, no code was changed so all tests are still passing.