Repository navigation
Add list of frame classes to main coordinates docs page - #9035
Conversation
|
Good idea! But I would suggest that we also move the lovely transform graph to this new section. This might actually be quite easy to do by adding the calculated |
Oh yea, good idea! |
|
|
||
| # Here, we override the module docstring so that sphinx renders the transform | ||
| # graph without the developer documentation in the main docstring above. | ||
| __doc__ = _transform_graph_docs |
There was a problem hiding this comment.
Seems fine as a work-around, though even nicer would be if somehow we can include it directly in the .rst file...
There was a problem hiding this comment.
I'm not sure if that's possible with the current implementation, as it is generated on-the-fly. Maybe @eteq has some thoughts?
There was a problem hiding this comment.
I looked around a bit more and it does seem possible to let sphinx display just the docstring of an item: https://stackoverflow.com/questions/7825263/including-docstring-in-sphinx-documentation
But perhaps this is better done separately. cc also @astrofrog, who seems to know this kind of stuff.
There was a problem hiding this comment.
But it's not the docstring of an item, it's a docstring generated by a function, right? Can we do this in a separate PR since this one works with the existing machinery?
There was a problem hiding this comment.
Yes, in a separate PR may be best.
There was a problem hiding this comment.
I agree with @adrn that the main problem is that it's generally difficult to do this kind of thing during the sphinx build process because it requires code execution. Options include:
- Doing it in the
conf.pyor a small custom sphinx extension - Using an otherwise empty module called
.../builtin_frames/transform_graph_docs.pythat just does:
from astropy.coordinates.builtin_frames import frame_transform_graph
__doc__ = make_transform_graph_docs(frame_transform_graph)
and use .. module:: transform_graph_docs to import it. But I'm not sure that's really much better than the current solution.
Thiat said, I agree this is better dealt with separately.
There was a problem hiding this comment.
I actually like the second solution! It helps to keep module __doc__ free for development stuff (which builtin_frames has already; see #8930)
7b79a83 to
cd372d5
Compare
|
Rebased, hopefully the html-docs build will work now? |
|
Hmm - the failure is real, but I'm confused by it. Any ideas? |
|
@adrn, I suspect your changes in |
Right, but I don't understand what could cause this - I just added a new title. As I mentioned in Sphinx, my local build has 152 warnings (Sphinx 2.1.2, Python 3.7.3) so it's not the easiest to debug... |
|
Hey, hey, seems like you fixed it! |
|
Now just needs a review :) |
Add list of frame classes to main coordinates docs page
Add list of frame classes to main coordinates docs page
Add list of frame classes to main coordinates docs page
|
This causes many docs warnings on LTS, so I'm inclined to not backport that far. |
This adds an auto-generated list of the built-in frame classes just before the full reference/API. I often want to see a text list of the frames, or need to click on the docs page for a frame class and scrolling through the full API is cumbersome.