Skip to content
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.

Sign up for GitHub

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

Jump to bottom

api.rst and autosummary replaces long modules and classes doc pages #258

Merged
merged 7 commits into from
Nov 4, 2016
Merged

api.rst and autosummary replaces long modules and classes doc pages #258

merged 7 commits into from
Nov 4, 2016

Conversation

wholmgren
Copy link
Member

I created a new api.rst to replace the modules.rst and classes.rst documentation pages. I dislike the fact that our existing documentation has all of the function, class, and method definitions on one huge page. #149 tried to use sphinx autosummary to make individual documentation pages, but I could never get it to work quite right (probably due to a sphinx bug). This manually created api.rst+autosummary actually does work, and it also groups functions and methods into categories instead of simply showing them in alphabetical order.

Rendered docs:

http://wholmgren-pvlib-python-new.readthedocs.io/en/manualdoc/api.html

I like this a lot better, but let me know if you disagree or if you find problems.

The only downside that I can think of is that new functions/methods/classes/modules have to be manually added to the documentation, but I think that's worth it.

@wholmgren wholmgren added this to the 0.4.2 milestone Oct 26, 2016
@jforbess
Copy link
Contributor

This is going to make it a lot easier to find the function I am looking
for, though I had gotten used to Command-F.

Thanks! I think it makes a lot of sense to have the Classes overview.

On Wed, Oct 26, 2016 at 3:14 PM, Will Holmgren notifications@github.com
wrote:

I created a new api.rst to replace the modules.rst and classes.rst
documentation pages. I dislike the fact that our existing documentation has
all of the function, class, and method definitions on one huge page. #149
#149 tried to use sphinx
autosummary to make individual documentation pages, but I could never get
it to work quite right (probably due to a sphinx bug). This manually
created api.rst+autosummary actually does work, and it also groups
functions and methods into categories instead of simply showing them in
alphabetical order.

Rendered docs:

http://wholmgren-pvlib-python-new.readthedocs.io/en/manualdoc/api.html

I like this a lot better, but let me know if you disagree or if you find
problems.

The only downside that I can think of is that new
functions/methods/classes/modules have to be manually added to the

documentation, but I think that's worth it.

You can view, comment on, or merge this pull request online at:

#258
Commit Summary

  • add initial api doc
  • add a bunch of functions and methods. almost all
  • add autosummary and no_scrollbars to conf
  • more modelchain and forecast stuff
  • remove old classes and module files. fix typos
  • remove cruft, add delta_t

File Changes

Patch Links:

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#258, or mute the thread
https://github.com/notifications/unsubscribe-auth/AH66Ae3cVwaVL06yEMGrbtm-BZ8GSeknks5q39DUgaJpZM4Khu6c
.

@adriesse
Copy link
Member

I still don't know how all this works, but I had noticed the big long
page and the new one looks like an improvement.

On 2016-10-27 0:14, Will Holmgren wrote:

I created a new api.rst to replace the modules.rst and classes.rst
documentation pages. I dislike the fact that our existing
documentation has all of the function, class, and method definitions
on one huge page. #149
#149 tried to use sphinx
autosummary to make individual documentation pages, but I could never
get it to work quite right (probably due to a sphinx bug). This
manually created api.rst+autosummary actually does work, and it also
groups functions and methods into categories instead of simply showing
them in alphabetical order.

Rendered docs:

http://wholmgren-pvlib-python-new.readthedocs.io/en/manualdoc/api.html

I like this a lot better, but let me know if you disagree or if you
find problems.

The only downside that I can think of is that new
functions/methods/classes/modules have to be manually added to the
documentation, but I think that's worth it.

    You can view, comment on, or merge this pull request online at:

#258

    Commit Summary

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#258, or mute the thread
https://github.com/notifications/unsubscribe-auth/AIlYQ2gU2mWRLCmCDrECzCcfUItxzCJsks5q39DUgaJpZM4Khu6c.

Photovoltaic Performance Labs Germany
Emmy-Noether-Str. 2
79110 Freiburg
Germany

+49-761-8973-5603 (Europe)
+49-174-532-7677 (Mobile)
+1-613-817-1652 (North America)

www.pvperformancelabs.com

@wholmgren
Copy link
Member Author

Thanks for the feedback!

@wholmgren wholmgren merged commit 5ddd9b1 into pvlib:master Nov 4, 2016
@wholmgren wholmgren mentioned this pull request Nov 4, 2016
Closed
@wholmgren wholmgren deleted the manualdoc branch September 9, 2017 20:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
documentation enhancement
Projects
None yet
Milestone
0.4.2
Development

Successfully merging this pull request may close these issues.
3 participants
@wholmgren @jforbess @adriesse