Skip to content

Rework documentation index page #5819

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.

Sign up for GitHub

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

Merged
merged 3 commits into from
Jun 19, 2019
Merged

Rework documentation index page #5819

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8260937
Rework documentation index page
davidfischer Jun 17, 2019
b0f0a80
Restructure features
davidfischer Jun 18, 2019
5a7c6f1
Move developer documentation under development/
davidfischer Jun 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 133 additions & 45 deletions docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,80 +43,185 @@ to help you create fantastic documentation for your project.
* **Importing your existing documentation**:
:doc:`Import guide <intro/import-guide>`


.. toctree::
:maxdepth: 2
:hidden:
:caption: First Steps
:caption: First steps

intro/getting-started-with-sphinx
intro/getting-started-with-mkdocs

intro/import-guide


.. _user-docs:
Getting started with Read the Docs
-----------------------------------

Learn more about configuring your automated documentation builds
and some of the core features of Read the Docs.

* **Overview of core features**:
:doc:`features`

* **Configure your documentation**:
:doc:`Configuration reference <config-file/index>` |
:doc:`webhooks` |
:doc:`badges` |
:doc:`Custom domains <custom_domains>`

* **Connecting with GitHub, BitBucket, or GitLab**:
:doc:`Connecting your account <connected-accounts>`

* **Read the Docs build and versioning process**:
:doc:`Build process <builds>` |
:doc:`Handling multiple docs versions <versions>`

* **Troubleshooting**:
:doc:`support` |
:doc:`Frequently asked questions <faq>`

.. toctree::
:maxdepth: 2
:caption: User Documentation
:maxdepth: 1
:hidden:
:caption: Getting started

versions
builds
features

config-file/index
webhooks
badges
custom_domains

connected-accounts

builds
versions

support
faq
config-file/index
guides/index
api/index
embed

.. _feature-docs:

Advanced features of Read the Docs
----------------------------------

Read the Docs offers many advanced features and options.
Learn more about these integrations and how you can get the most
out of your documentation and Read the Docs.

* **Advanced project configuration**:
:doc:`subprojects` |
:doc:`Single version docs <single_version>` |
:doc:`Privacy levels <privacy>`

* **Multi-language documentation**:
:doc:`Translations and localization <localization>`

* **Redirects**:
:doc:`User defined redirects <user-defined-redirects>` |
:doc:`Automatic redirects <automatic-redirects>`

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about putting this in the Troubleshooting section?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


* **Extending Read the Docs**:
:doc:`REST API <api/index>` |
:doc:`embed`

.. toctree::
:maxdepth: 2
:hidden:
:glob:
:caption: Feature Documentation
:caption: Advanced features

webhooks
badges
custom_domains
localization
vcs
subprojects
conda
canonical
single_version
privacy

localization

user-defined-redirects
automatic-redirects

guides/index

api/index
embed

vcs
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

conda
canonical
features/*

.. _about-docs:

The Read the Docs project and organization
------------------------------------------

Learn about Read the Docs, the project and the company,
and find out how you can get involved and contribute to the development and success
of Read the Docs and the larger software documentation ecosystem.

* **Getting involved with Read the Docs**:
:doc:`Contributing <contribute>` |
:doc:`roadmap` |
:doc:`gsoc` |
:doc:`Code of conduct <code-of-conduct>`

* **Policies & Process**:
:doc:`security` |
:doc:`Privacy policy <privacy-policy>` |
:doc:`DMCA takedown policy <dmca/index>` |
:doc:`Policy for abandoned projects <abandoned-projects>` |
:doc:`Release notes & changelog <changelog>`

* **The people and philosophy behind Read the Docs**:
:doc:`Team <team>` |
:doc:`Open source philosophy <open-source-philosophy>` |
:doc:`Our story <story>`

* **Financial and material support**:
:doc:`advertising/index` |
:doc:`Sponsors <sponsors>`

* **Read the Docs for business**:
:doc:`Support and additional features <commercial/index>`

* **Running your own version of Read the Docs**:
:doc:`Private installations <custom_installs/index>`


.. toctree::
:maxdepth: 1
:hidden:
:caption: About Read the Docs

contribute
roadmap
team
gsoc
code-of-conduct

security
privacy-policy
advertising/index
sponsors
dmca/index
abandoned-projects
changelog

team
open-source-philosophy
story
abandoned-projects
dmca/index

.. _dev-docs:
advertising/index
sponsors

commercial/index

custom_installs/index


.. toctree::
:maxdepth: 1
:caption: Developer Documentation
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

:caption: Developer documentation

changelog
install
development/search
architecture
Expand All @@ -129,22 +234,5 @@ to help you create fantastic documentation for your project.
settings
i18n
issue-labels
security
design
RTD Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>

.. _commercial-docs:

.. toctree::
:maxdepth: 2
:caption: Commercial Documentation

commercial/index

.. _custom-docs:

.. toctree::
:maxdepth: 2
:caption: Custom Install Documentation

custom_installs/index