New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Auto-generate API docs #356

Merged
merged 6 commits into from Apr 30, 2014

Conversation

Projects
None yet
3 participants
@stefanv
Contributor

stefanv commented Apr 27, 2014

No description provided.

These files were obtained from
http://groups.google.com/group/sphinx-dev/browse_thread/thread/595ef2eff60084c5/

This comment has been minimized.

@arokem

arokem Apr 28, 2014

Member

"The requested topic cannot be found. It might have been deleted"

api-clean:
cd reference && rm -rf *.rst
api:

This comment has been minimized.

@arokem

arokem Apr 28, 2014

Member

You might want to add this to the documentation above

@@ -33,10 +33,18 @@ help:
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean: examples-clean
clean: api-clean examples-clean

This comment has been minimized.

@arokem

arokem Apr 28, 2014

Member

This will generate an error if you haven't run make api first.

@arokem

This comment has been minimized.

Member

arokem commented Apr 28, 2014

Cool. Is the goal here just to remove those calls to the automodule directive, or does this actually do something different?

@stefanv

This comment has been minimized.

Contributor

stefanv commented Apr 28, 2014

Thanks, all done.

Now there's quite a bit of work to do on getting the docs themselves cleaned up! For one, we need to start looking at introducing __all__, so that the documentation engine can know which functions are meant to be internal and which are exposed to the user (you'll see there are a lot of references to functions that actually live in numpy, python, etc.)

@stefanv

This comment has been minimized.

Contributor

stefanv commented Apr 28, 2014

@arokem The goal is to not have to update the references/*.rst files whenever we change code, and also to guarantee that the API documentation reflects what's actually inside the code base.

@stefanv

This comment has been minimized.

Contributor

stefanv commented Apr 28, 2014

You'll see that the generated files still contain automodule and autosummary calls.

@Garyfallidis

This comment has been minimized.

Member

Garyfallidis commented Apr 29, 2014

Super @stefanv !!!! 👍 👍 👍
I just compiled locally the docs and they look so much better!! Will have a more careful look tomorrow and possibly merge this baby!!! And yes for sure we can do more cleanup but it will be so much easier from now on.
Thanks man!!

@stefanv

This comment has been minimized.

Contributor

stefanv commented Apr 29, 2014

My pleasure :)

Garyfallidis added a commit that referenced this pull request Apr 30, 2014

@Garyfallidis Garyfallidis merged commit 2173230 into nipy:master Apr 30, 2014

1 check passed

continuous-integration/travis-ci The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment