Apidocs #2383

Closed
wants to merge 13 commits into
from

Projects

None yet

6 participants

@takluyver
Owner

Not ready for merge.

This is something we discussed briefly a couple of weeks ago - should we move from fully auto-generated API docs to something a bit more manual, forcing us to be clearer about what is the public API?

I made a start towards that, but I wanted to check what we think of the idea and the details before I spend more time on it. I used the auto-generated API docs with some modifications:

  • Rearranged into a hierarchical structure matching the package structure (core/history.txt rather than IPython.core.history.txt)
  • Simplifying subheadings
  • Not describing local utility functions and classes (like Bunch).
  • Removing inheritance diagrams except where they're interesting (e.g. that for ultratb is interesting)
  • Removing the :inherited-members: option from autoclass documentation (classes that derive from Configurable, for example, inherit a lot of confusing methods)
  • Removing the .. automethod:: __init__ documentation where __init__ doesn't have a docstring.
@bfroehle bfroehle and 1 other commented on an outdated diff Sep 4, 2012
docs/source/api/core/alias.txt
@@ -0,0 +1,38 @@
+.. AUTO-GENERATED FILE -- DO NOT EDIT!
bfroehle
bfroehle Sep 4, 2012 Contributor

Did you mean to remove this comment?

takluyver
takluyver Sep 4, 2012 Owner

Yes, thanks. I must have missed this one.

This pull request fails (merged fda39e2 into c678a87).

@bfroehle bfroehle and 1 other commented on an outdated diff Sep 4, 2012
IPython/core/history.py
@@ -721,10 +721,10 @@ def stop(self):
def extract_hist_ranges(ranges_str):
"""Turn a string of history ranges into 3-tuples of (session, start, stop).
- Examples
- --------
- list(extract_input_ranges("~8/5-~7/4 2"))
- [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]
+ Example::
+
+ >>> list(extract_input_ranges("~8/5-~7/4 2"))
bfroehle
bfroehle Sep 4, 2012 Contributor

Now that this is getting tested, it'll have to be extract_hist_ranges (instead of extract_input_ranges).

takluyver
takluyver Sep 4, 2012 Owner

Thanks, that should be fixed in the next commit.

This pull request fails (merged 63dc154 into c678a87).

This pull request fails (merged ca3de81 into c678a87).

This pull request passes (merged 381d567 into c678a87).

Owner
fperez commented Sep 13, 2012

I think in the long run, this is necessary. Our current setup is a bit too chaotic and leaves users with an incomprehensible impact surface for what IPython is as a library.

Given that I don't think the current autogen docs are very good as they are, I'm totally +1 on moving forward with this, even if it takes a while to get it where we'd be completely happy.

Owner

This is important, but should be close the PR and open an issue to track this (> 2 months inactivity)?

Owner

Yes, if you'd prefer. I'm not convinced that this is the right approach - it's a lot of work to do this, as evidenced by the fact that I didn't even finish the docs for IPython.core. But I do think we need to improve our API docs, and work out what parts we really consider the API, and what is implementation details.

@takluyver takluyver referenced this pull request Nov 24, 2012
Merged

Revamp API docs #2616

Owner
Carreau commented Dec 4, 2012

@takluyver Was #2616 a replacement of this one ? can it be closed ?

Owner

Yes, good point.

@takluyver takluyver closed this Dec 4, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment