Repository navigation
Template for subpackage docs - #218
Conversation
There was a problem hiding this comment.
conviniently -> conveniently
also the comma after "used" is unnecessary
|
Looks fine other than my one nitpick. |
|
One quick thought -- maybe call it |
There was a problem hiding this comment.
I agree, the table of contents will look very busy if each line contains 'Documentation'
|
This looks good to me! |
|
We should probably resolve some of the issues in #219 before locking this in. |
- Update subpackage docs following format suggestion from pull request issue astropy#218. - Added much more useful introduction and Getting Started section, emphasizing high level simple stuff first. - Re-organized page on constructing tables to put the simpler / more likely cases first. - Added more detail in places including explanation of new- and old- style formatting.
|
Just for clarification, where should the API be? You had a separate API/Reference section before, but you removed the header to avoid duplication with the auto-generated 'Reference/API' title, so it's no longer clear where the API should be. |
|
|
|
@eteq - yes, the |
|
Could we simply take the "Reference/API" title out of the |
|
@kbarbary - that would be easy enough, and I guess it would be more explicit... I put it in there mainly so people would always use the same order (e.g. Reference/API vs. API/Reference). @astrofrog, @taldcroft, does that seem reasonable? If so I'll update this PR with that change. |
|
@eteq - I think it would indeed be clearer to have the title explicitly included in the template and taken out of automodapi. |
|
@eteq - agree on having the title in the template instead of automodapi. |
|
@astrofrog good point - I'll update this PR with the small points above, fix the conflict and merge early next week. |
|
This has now been rebased against master, and updated to take References/API out of automodapi and into the template. If there are no objections, I'll merge this tomorrow. |
|
This is OK but |
|
@taldcroft - Thanks - I had updated |
|
Looks good - feel free to merge! |
- Update subpackage docs following format suggestion from pull request issue astropy#218. - Added much more useful introduction and Getting Started section, emphasizing high level simple stuff first. - Re-organized page on constructing tables to put the simpler / more likely cases first. - Added more detail in places including explanation of new- and old- style formatting.
Template for subpackage docs
Template for subpackage docs
Update hero logo to use new "The Astropy Project" branding
This PR adds a template file for use when generating new subpackages (and hopefully, eventually, for homogenizing all of the subpackage documentation). It also re-writes
config.rstas sort of a "case study" in how this template works.Any thoughts on changes that should be made to this template?
One thing to note that was an arbitrary choice I made: This template assumes that any time you have multi-page documentation, the main page is in the
docsdirectory, while only the sub-pages are inside a directory. E.g., if you have a subpackage namedmysubpkg, with two sub-pagessub1.rstandsub2.rst, the template assumes you would create the filesdocs/mysubpkg.rst,docs/mysubpkg/sub1.rst, anddocs/mysubpkg/sub2.rst. An alternative is to instead place the base document in the directory - e.g. the first file is insteaddocs/mysubpkg/mysubpkg.rst.I prefer the current way (the first example above), as it makes all the subpackage documentation have a base file in the same directory, so e.g. the main TOCtree in
index.rstdoesn't have to be altered if later someone adds subpages. But if anyone feels strongly about it, I can change this.