Rework documentation index page #5819
Conversation
davidfischer
added
the
PR: work in progress
docs/index.rst
Outdated
| api/index | ||
| embed | ||
|
|
||
| vcs |
There was a problem hiding this comment.
These four sections (vcs, conda, etc.) seem to fit better in docs/guides. I propose moving them there. I also think docs/features/embed should be just a section of docs/embed rather than its own page.
There was a problem hiding this comment.
They might need a bit of a rewrite/reframing of the content, but I agree the "Feature" documentation has always felt a bit weird, and should probably just be a list of features and then guides for how to use them well.
|
|
||
| .. toctree:: | ||
| :maxdepth: 1 | ||
| :caption: Developer Documentation |
There was a problem hiding this comment.
Other than the security docs and changelog which I moved out of this section, I think that the developer docs should not be on the front docs page. Instead, I propose expanding docs/contribute and putting this toctree into a section there. I also think all of these RST files should be under docs/development.
There was a problem hiding this comment.
Makes sense. We really need to create a git-mapped redirect app, to make creating redirects for ourselves simpler.
| :doc:`Automatic redirects <automatic-redirects>` | ||
|
|
||
| * **Topic specific guides**: | ||
| :doc:`How-to guides <guides/index>` |
There was a problem hiding this comment.
What about putting this in the Troubleshooting section?
There was a problem hiding this comment.
These guides (eg. "managing translations" or "adding custom JS/CSS to sphinx") are not exactly troubleshooting. That's not to say we can't come up with something better than "how-to guides".
Maybe we could just have a full sentence giving more details about the guides. Django does something like that in their documentation:
Travis has a whole section on their homepage for "Language specific guides":
Our guides are a little too varied for what Travis does but maybe something similar to what Django does.
I think this stage will be covered by #5771 and now we can care about the first steps that you are doing here. |
stsewd
removed
the
PR: work in progress
|
Before this is merged, I'm going to try to do a couple things. I should have them done today:
|
- Move basic features that don't fit under guides/ - Remove the embed documentation which is broken
- Fix dangling references
|
I did some minor moving things around but we should probably setup a few redirects once this is deployed (not just merged but deployed to Guides that moved
Development docs that moved
|
|
This also closes #2667 because it removed the embed API docs which were broken. |
|
We also should redirect |
Do you mean to redirect |
|
No, we need to also add those redirects to the |
|
Currently, when setting a page redirect, it applies to all versions:
|
|
Sounds good -- I'm happy to ship this once the redirects are in place. 👍 |
Goals
This structure was influenced heavily by the Django documentation but I definitely referred to other documentation including for Travis, CircleCI, and Heroku.
Fixes: #5675
Fixes: #2667