Repository navigation
Update tools and utils to the subpackage template form - #271
Conversation
There was a problem hiding this comment.
Wouldn't it make sense to keep a utils directory rather than having a bunch of .rst files at the top level? Just a personal preference, I guess.
There was a problem hiding this comment.
My idea was that if there's more than one .rst file, the directory definitely makes sense. But the use of :automodapi: here removes the need for distinct api_*.rst files, so right now only one file is needed. If in the future someone wants to make a separate page, then it should be moved into its own directory.
This point should definitely be documented somewhere, though - where do you think it goes... The documentation guidelines, the subpackage template, or a commented area in the .rst files?
|
Looks fine, other than the question of directory layout. |
|
@iguananaut @astrofrog @taldcroft - as people who've recently worked with updating to this doc standard: what do you think of the discussion above regarding separate directories? Is it ok as I've done here (single files don't get directories, but we move them into directories once someone wants a second file)? |
|
@eteq - part of me thinks we should just put the pages in the right place, just in case anyone links to them - i.e. if someone links to docs.astropy.org/cosmology.html, the link will break if we then move the page to docs.astropy.org/cosmology/index.html. |
|
I agree with @astrofrog that we should have a structure that avoids future link breakage to the extent possible, certainly at the top levels of our docs. One could even take this to the level of saying that every top-level section in AstroPy should be a directory, which makes every such topic available as |
|
+1; if we think it might go into a separate directory later it's preferable to go ahead and lay it out that way. |
|
+1 on separate directories |
|
I hadn't thought about the link-breaking problem - very good point. With that in mind, I agree that it makes more sense to just have them start out in a directory. I'll go ahead and merge this so we have these docs in place, and then create a new PR to put everything in its own directory. |
Update tools and utils to the subpackage template form
…empl Update tools and utils to the subpackage template form
Update versions
This updates the tools and utils package to reflect the standard form. Note that this isn't fully true, because
utilsis such a grab-bag that it didn't really make sense how to "use" the whole module. Similarly,toolsis pretty unpopulated so far, so I left a commented-out using section to later be brought back in.