Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework documentation index page #5819

Merged
merged 3 commits into from Jun 19, 2019
Merged

Conversation

@davidfischer
Copy link
Contributor

@davidfischer davidfischer commented Jun 17, 2019

Goals

  • Make sure the documentation is primarily focused on users (developers of RTD are secondary or lower)
  • Explain the various sections in a bit more detail and guide users better than a simple toctree
  • At this stage, I was not attempting to significantly restructure, rewrite, or remove any docs.

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

docs/index.rst Outdated
api/index
embed

vcs
Copy link
Contributor Author

@davidfischer davidfischer Jun 17, 2019

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.

Copy link
Member

@ericholscher ericholscher Jun 18, 2019

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
Copy link
Contributor Author

@davidfischer davidfischer Jun 17, 2019

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.

Copy link
Member

@ericholscher ericholscher Jun 18, 2019

Makes sense. We really need to create a git-mapped redirect app, to make creating redirects for ourselves simpler.

Copy link
Member

@stsewd stsewd left a comment

Looks awesome!

:doc:`Automatic redirects <automatic-redirects>`

* **Topic specific guides**:
:doc:`How-to guides <guides/index>`
Copy link
Member

@stsewd stsewd Jun 17, 2019

What about putting this in the Troubleshooting section?

Copy link
Contributor Author

@davidfischer davidfischer Jun 17, 2019

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:

Screen Shot 2019-06-17 at 4 45 12 PM

Travis has a whole section on their homepage for "Language specific guides":

Screen Shot 2019-06-17 at 4 44 57 PM

Our guides are a little too varied for what Travis does but maybe something similar to what Django does.

@humitos
Copy link
Member

@humitos humitos commented Jun 18, 2019

At this stage, I was not attempting to significantly restructure, rewrite, or remove any docs.

I think this stage will be covered by #5771 and now we can care about the first steps that you are doing here.

Copy link
Member

@ericholscher ericholscher left a comment

This is way better. 💯

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jun 18, 2019

Before this is merged, I'm going to try to do a couple things. I should have them done today:

  • Move a few things (vcs, conda, etc.) under guides
  • Move developer documentation under contributing

- Move basic features that don't fit under guides/
- Remove the embed documentation which is broken
@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jun 18, 2019

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 /en/stable):

Guides that moved

  • /canonical.html -> /guides/canonical.html
  • /conda.html -> /guides/conda.html
  • /vcs.html -> /guides/vcs.html

Development docs that moved

  • /design.html -> /development/design.html
  • /design/apiv3.html -> /development/design/apiv3.html
  • /design/in-doc-search-ui.html -> /development/design/in-doc-search-ui.html
  • /design/index.html -> /development/design/index.html
  • /design/pr-builder.html -> /development/design/pr-builder.html
  • /design/theme-context.html -> /development/design/theme-context.html
  • /design/yaml-file.html -> /development/design/yaml-file.html
  • /docs.html -> /development/docs.html
  • /i18n.html -> /development/i18n.html
  • /install.html -> /development/install.html
  • /issue-labels.html -> /development/issue-labels.html
  • /settings.html -> /development/settings.html
  • /symlinks.html -> /development/symlinks.html
  • /tests.html -> /development/tests.html

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jun 18, 2019

This also closes #2667 because it removed the embed API docs which were broken.

@ericholscher
Copy link
Member

@ericholscher ericholscher commented Jun 18, 2019

We also should redirect /en/latest/ as well :/

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jun 18, 2019

We also should redirect /en/latest/ as well :/

Do you mean to redirect /en/latest to /en/stable?

@ericholscher
Copy link
Member

@ericholscher ericholscher commented Jun 18, 2019

No, we need to also add those redirects to the latest version.

@davidfischer
Copy link
Contributor Author

@davidfischer davidfischer commented Jun 18, 2019

Currently, when setting a page redirect, it applies to all versions:

Screen Shot 2019-06-18 at 2 56 46 PM

@ericholscher
Copy link
Member

@ericholscher ericholscher commented Jun 19, 2019

Sounds good -- I'm happy to ship this once the redirects are in place. 👍

@davidfischer davidfischer merged commit 4589a59 into master Jun 19, 2019
2 checks passed
@davidfischer davidfischer deleted the davidfischer/restructure-docs-index branch Jun 19, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

4 participants