diff --git a/docs/contribute.rst b/docs/contribute.rst index 4d4df04b7a9..abdf943413a 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -25,7 +25,7 @@ Contributing to development If you want to deep dive and help out with development on Read the Docs, then first get the project installed locally according to the -:doc:`Installation Guide `. After that is done we +:doc:`Installation Guide `. After that is done we suggest you have a look at tickets in our issue tracker that are labelled `Good First Issue`_. These are meant to be a great way to get a smooth start and won't put you in front of the most complex parts of the system. @@ -103,7 +103,35 @@ Contributing to documentation Documentation for Read the Docs itself is hosted by Read the Docs at https://docs.readthedocs.io (likely the website you are currently reading). There are guidelines around writing and formatting documentation for the project. -For full details, including how to build it, see :doc:`docs`. +For full details, including how to build it, see :doc:`/development/docs`. + + +Developer documentation +----------------------- + +These are guides and helpful documentation to running your own local version of Read the Docs +for development or taking the open source Read the Docs codebase +for your own :doc:`custom installation `. + +.. toctree:: + :maxdepth: 1 + + development/install + development/search + development/architecture + development/tests + development/docs + development/design/index + development/standards + development/buildenvironments + development/symlinks + development/settings + development/i18n + development/issue-labels + development/design + RTD Theme + + Triaging tickets ---------------- @@ -244,7 +272,7 @@ few more at hand to further categorize issues. handled during a sprint. They are very focused and encapsulated. For a full list of available labels and their meanings, see -:doc:`issue-labels`. +:doc:`/development/issue-labels`. Helpful links for triaging ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/custom_installs/customization.rst b/docs/custom_installs/customization.rst index f58420040e3..60c1657f0f8 100644 --- a/docs/custom_installs/customization.rst +++ b/docs/custom_installs/customization.rst @@ -1,7 +1,7 @@ Customizing your install ======================== -Read the Docs has a lot of :doc:`/settings` that help customize your install. +Read the Docs has a lot of :doc:`/development/settings` that help customize your install. This document will outline some of the more useful ways that these can be combined. Have a local settings file diff --git a/docs/architecture.rst b/docs/development/architecture.rst similarity index 100% rename from docs/architecture.rst rename to docs/development/architecture.rst diff --git a/docs/design.rst b/docs/development/design.rst similarity index 94% rename from docs/design.rst rename to docs/development/design.rst index 142f78d35b8..1a153ee848c 100644 --- a/docs/design.rst +++ b/docs/development/design.rst @@ -33,7 +33,7 @@ documentation using the default RTD style. Contributing ------------ -Contributions should follow the :doc:`contribute` guidelines where applicable -- ideally you'll +Contributions should follow the :doc:`../contribute` guidelines where applicable -- ideally you'll create a pull request against the `Read the Docs GitHub project`_ from your forked repo and include a brief description of what you added / removed / changed, as well as an attached image (you can just take a screenshot and drop it into the PR creation form) of the effects of your changes. diff --git a/docs/design/apiv3.rst b/docs/development/design/apiv3.rst similarity index 100% rename from docs/design/apiv3.rst rename to docs/development/design/apiv3.rst diff --git a/docs/design/in-doc-search-ui.rst b/docs/development/design/in-doc-search-ui.rst similarity index 96% rename from docs/design/in-doc-search-ui.rst rename to docs/development/design/in-doc-search-ui.rst index 3a2a05837d1..656977c5475 100644 --- a/docs/design/in-doc-search-ui.rst +++ b/docs/development/design/in-doc-search-ui.rst @@ -18,9 +18,9 @@ This is a GSoC'19 project. The final result may look something like this: -.. figure:: ../_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif +.. figure:: ../../_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif :align: center - :target: ../_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif + :target: ../../_static/images/design-docs/in-doc-search-ui/in-doc-search-ui-demo.gif Short demo @@ -49,7 +49,7 @@ Existing Search Implementation We have a detailed documentation explaing the underlying architecture of our search backend and how we index documents to our Elasticsearch index. -You can read about it :doc:`here <../development/search>`. +You can read about it :doc:`here <../search>`. Proposed Architecture for In-Doc Search UI diff --git a/docs/design/index.rst b/docs/development/design/index.rst similarity index 100% rename from docs/design/index.rst rename to docs/development/design/index.rst diff --git a/docs/design/pr-builder.rst b/docs/development/design/pr-builder.rst similarity index 100% rename from docs/design/pr-builder.rst rename to docs/development/design/pr-builder.rst diff --git a/docs/design/theme-context.rst b/docs/development/design/theme-context.rst similarity index 100% rename from docs/design/theme-context.rst rename to docs/development/design/theme-context.rst diff --git a/docs/design/yaml-file.rst b/docs/development/design/yaml-file.rst similarity index 100% rename from docs/design/yaml-file.rst rename to docs/development/design/yaml-file.rst diff --git a/docs/docs.rst b/docs/development/docs.rst similarity index 100% rename from docs/docs.rst rename to docs/development/docs.rst diff --git a/docs/i18n.rst b/docs/development/i18n.rst similarity index 100% rename from docs/i18n.rst rename to docs/development/i18n.rst diff --git a/docs/install.rst b/docs/development/install.rst similarity index 97% rename from docs/install.rst rename to docs/development/install.rst index b9cfc136ab7..e707878fcfd 100644 --- a/docs/install.rst +++ b/docs/development/install.rst @@ -178,9 +178,9 @@ Further steps By now you can trigger builds on your local environment, to encapsulate the build process inside a Docker container, -see :doc:`development/buildenvironments`. +see :doc:`buildenvironments`. For building this documentation, see :doc:`docs`. -And for setting up for the front end development, see :doc:`development/standards`. +And for setting up for the front end development, see :doc:`standards`. diff --git a/docs/issue-labels.rst b/docs/development/issue-labels.rst similarity index 100% rename from docs/issue-labels.rst rename to docs/development/issue-labels.rst diff --git a/docs/settings.rst b/docs/development/settings.rst similarity index 100% rename from docs/settings.rst rename to docs/development/settings.rst diff --git a/docs/symlinks.rst b/docs/development/symlinks.rst similarity index 100% rename from docs/symlinks.rst rename to docs/development/symlinks.rst diff --git a/docs/tests.rst b/docs/development/tests.rst similarity index 100% rename from docs/tests.rst rename to docs/development/tests.rst diff --git a/docs/embed.rst b/docs/embed.rst deleted file mode 100644 index 425eb5bbc16..00000000000 --- a/docs/embed.rst +++ /dev/null @@ -1,157 +0,0 @@ -Embed API -========= - -Read the Docs allow you to embed content from any of the projects we host. -This allows for content re-use across sites, -making sure the content is always up to date. - -Workflow --------- - -There are many uses of our Embed API. -One of our favorites is for inline help. -We have started using this on Read the Docs itself to provide inline help on our main site pages. -This allows us to keep the official documentation as the single source of truth, -while having great inline help in our application as well. - -We recommend you point at **tagged releases** instead of ``latest``. -Tags don't change over time, -so you don't have to worry about the content you are embedding disappearing. - -.. note:: All relative links to pages contained in the remote content will continue to point at the remote page. - -How to use it -------------- - - -Sphinx Extension -~~~~~~~~~~~~~~~~ - -You can embed content directly in Sphinx with builds on Read the Docs. -We support default configuration variables for your ``conf.py``: - -* readthedocs_embed_project -* readthedocs_embed_version -* readthedocs_embed_doc - -These are overridable per-call as well. -Then you simply use the directive: - -.. code-block:: restructuredtext - - # All arguments - .. readthedocs-embed:: - :project: myproject - :version: latest - :doc: index - :section: User Guide - - # Or with some defaults - .. readthedocs-embed:: - :doc: index - :section: User Guide - - -Javascript -~~~~~~~~~~ - -We provide a Javascript library that you can embed on any site. -An example: - -.. code-block:: html - - - - - - - -
- (Help) -
- - -This will provide a pop-out for a user with the ``How we envision versions working`` section of the ``versions`` page. -You can see this in action here: - -.. raw:: html - - - - - - -
- (Help) -
-
-
- -.. note:: All Read the Docs pages already have the library loaded, so you can ignore the ``link`` and first ``script`` tags on all documentation. - - - -.. warning:: We currently do not provide caching on this API. - If the remote source you are including changes their page structure or deletes the content, - your embed will break. - - In Version 2 of this API we will provide a full-formed workflow that will stop this from happening. - - - -Example API Response --------------------- - -Pure API use will return JSON: - -.. code-block:: javascript - - { - "content": [ - "
\n

Encoded Data?\u00b6

\n

Requests automatically decompresses gzip-encoded responses, and does\nits best to decode response content to unicode when possible.

\n

You can get direct access to the raw response (and even the socket),\nif needed as well.

\n
" - ], - "wrapped": [ - "\n
\n
\n
\n

Encoded Data?\u00b6

\n

Requests automatically decompresses gzip-encoded responses, and does\nits best to decode response content to unicode when possible.

\n

You can get direct access to the raw response (and even the socket),\nif needed as well.

\n
\n
\n
\n Embedded from Read the Docs\n
\n
\n " - ], - "meta": { - "project": "requests", - "doc": "community/faq", - "section": "Encoded Data?", - "version": "latest", - "modified": "Wed, 04 Feb 2015 08:59:59 GMT" - }, - "url": "/docs/requests/en/latest/community/faq.html", - "headers": [ - { - "Frequently Asked Questions": "#" - }, - { - "Encoded Data?": "#encoded-data" - }, - { - "Custom User-Agents?": "#custom-user-agents" - }, - { - "Why not Httplib2?": "#why-not-httplib2" - }, - { - "Python 3 Support?": "#python-3-support" - }, - { - "What are \u201chostname doesn\u2019t match\u201d errors?": "#what-are-hostname-doesn-t-match-errors" - } - ] - } \ No newline at end of file diff --git a/docs/features.rst b/docs/features.rst index 9650d2cd671..442c20240be 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -8,7 +8,7 @@ GitHub, Bitbucket and GitLab Integration We now support linking by default in the sidebar. It links to the page on your host, which should help people quickly update typos and send pull requests to contribute to project documentation. -More information can be found in the :doc:`vcs` page. +More information can be found in :doc:`guides/vcs`. Auto-updating ------------- @@ -18,14 +18,15 @@ The :doc:`webhooks` page talks about the different ways you can ping RTD to let Internationalization -------------------- -Read the Docs itself is localized, and we support documentation translated into multiple languages. Read more on the :doc:`localization` and :doc:`i18n` pages. +Read the Docs itself is localized, and we support documentation translated into multiple languages. +Read more on the :doc:`localization` and :doc:`development/i18n` pages. Canonical URLs -------------- Canonical URLs give your docs better search performance, by pointing all URLs to one version. This also helps to solve the issues around users landing on outdated versions of documentation. -More information can be found in the :doc:`canonical` page. +More information can be found in the :doc:`guides/canonical` page. Versions -------- diff --git a/docs/features/embed.rst b/docs/features/embed.rst deleted file mode 100644 index 8ab74623d51..00000000000 --- a/docs/features/embed.rst +++ /dev/null @@ -1,28 +0,0 @@ -Content Embedding -================= - -Using the `Read the Docs JavaScript Client`_, or with basic calls to our REST -API, you can retrieve embeddable content for use on your own site. Content is -embedded in an iframe element, primarily for isolation. To get example usage of -the API, see the tools tab under an active project and select the page and -section that you would like to test. - -.. note:: - - The client library is still alpha quality. This guide is still lacking - advanced usage of the library, and information on styling the iframe - content. We plan to have more usage outlined as the library matures. - -Example usage of the client library: - -.. code-block:: javascript - - var embed = Embed(); - embed.section( - 'read-the-docs', 'latest', 'features', 'Read the Docs features', - function (section) { - section.insertContent($('#help')); - } - ); - -.. _`Read the Docs JavaScript Client`: https://github.com/agjohnson/readthedocs-client-js diff --git a/docs/gsoc.rst b/docs/gsoc.rst index 7b67b017c59..cadbcfb40d1 100644 --- a/docs/gsoc.rst +++ b/docs/gsoc.rst @@ -29,7 +29,7 @@ the more likely we are to choose your application! Getting Started --------------- -The :doc:`/install` doc is probably the best place to get going. +The :doc:`/development/install` doc is probably the best place to get going. It will walk you through getting a basic environment for Read the Docs setup. Then you can look through our :doc:`/contribute` doc for information on how to get started contributing to RTD. diff --git a/docs/canonical.rst b/docs/guides/canonical.rst similarity index 100% rename from docs/canonical.rst rename to docs/guides/canonical.rst diff --git a/docs/conda.rst b/docs/guides/conda.rst similarity index 93% rename from docs/conda.rst rename to docs/guides/conda.rst index e1c2cc45f95..4d5565c22b4 100644 --- a/docs/conda.rst +++ b/docs/guides/conda.rst @@ -14,7 +14,7 @@ This work was funded by `Clinical Graphics`_ -- many thanks for their support of Activating Conda ---------------- -Conda support is available using a :doc:`config-file/index`, see :ref:`config-file/v2:conda`. +Conda support is available using a :doc:`../config-file/index`, see :ref:`config-file/v2:conda`. This Conda environment will also have Sphinx and other build time dependencies installed. It will use the same order of operations that we support currently: diff --git a/docs/features/sitemaps.rst b/docs/guides/sitemaps.rst similarity index 100% rename from docs/features/sitemaps.rst rename to docs/guides/sitemaps.rst diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst index 38acb0cd2e7..0c174202913 100644 --- a/docs/guides/specifying-dependencies.rst +++ b/docs/guides/specifying-dependencies.rst @@ -36,7 +36,7 @@ Using a conda environment file If using conda, the dependencies can be specified in the `conda environment file`_: ``environment.yml`` . -More on Read the Doc's conda support: :doc:`/conda`. +More on Read the Doc's conda support: :doc:`conda`. .. _`pip user guide`: https://pip.pypa.io/en/stable/user_guide/#requirements-files .. _`conda environment file`: https://conda.io/docs/user-guide/tasks/manage-environments.html diff --git a/docs/vcs.rst b/docs/guides/vcs.rst similarity index 95% rename from docs/vcs.rst rename to docs/guides/vcs.rst index 4a1f2cd326b..08356cf32d0 100644 --- a/docs/vcs.rst +++ b/docs/guides/vcs.rst @@ -3,7 +3,7 @@ Version Control System Integration .. note:: - We :doc:`plan to implement a new approach ` regarding the Theme Context as a whole, + We :doc:`plan to implement a new approach ` regarding the Theme Context as a whole, although the VCS documentation page will still be valid, we prefer the users to move in that direction. diff --git a/docs/index.rst b/docs/index.rst index 73ceb88ed15..07b10228840 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,108 +43,170 @@ to help you create fantastic documentation for your project. * **Importing your existing documentation**: :doc:`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 ` | + :doc:`webhooks` | + :doc:`badges` | + :doc:`Custom domains ` + +* **Connecting with GitHub, BitBucket, or GitLab**: + :doc:`Connecting your account ` + +* **Read the Docs build and versioning process**: + :doc:`Build process ` | + :doc:`Handling multiple docs versions ` + +* **Troubleshooting**: + :doc:`support` | + :doc:`Frequently asked questions ` .. 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 ` | + :doc:`Privacy levels ` + +* **Multi-language documentation**: + :doc:`Translations and localization ` + +* **Redirects**: + :doc:`User defined redirects ` | + :doc:`Automatic redirects ` + +* **Topic specific guides**: + :doc:`How-to guides ` + +* **Extending Read the Docs**: + :doc:`REST API ` .. 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 - features/* -.. _about-docs: + guides/index + + api/index + + +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 ` | + :doc:`roadmap` | + :doc:`gsoc` | + :doc:`Code of conduct ` + +* **Policies & Process**: + :doc:`security` | + :doc:`Privacy policy ` | + :doc:`DMCA takedown policy ` | + :doc:`Policy for abandoned projects ` | + :doc:`Release notes & changelog ` + +* **The people and philosophy behind Read the Docs**: + :doc:`Team ` | + :doc:`Open source philosophy ` | + :doc:`Our story ` + +* **Financial and material support**: + :doc:`advertising/index` | + :doc:`Sponsors ` + +* **Read the Docs for business**: + :doc:`Support and additional features ` + +* **Running your own version of Read the Docs**: + :doc:`Private installations ` + .. toctree:: :maxdepth: 1 + :hidden: :caption: About Read the Docs contribute roadmap - team gsoc code-of-conduct + + security privacy-policy - advertising/index - sponsors - open-source-philosophy - story - abandoned-projects dmca/index - -.. _dev-docs: - -.. toctree:: - :maxdepth: 1 - :caption: Developer Documentation - + abandoned-projects changelog - install - development/search - architecture - tests - docs - design/index - development/standards - development/buildenvironments - symlinks - settings - i18n - issue-labels - security - design - RTD Theme -.. _commercial-docs: + team + open-source-philosophy + story -.. toctree:: - :maxdepth: 2 - :caption: Commercial Documentation + advertising/index + sponsors commercial/index -.. _custom-docs: - -.. toctree:: - :maxdepth: 2 - :caption: Custom Install Documentation - custom_installs/index + diff --git a/docs/localization.rst b/docs/localization.rst index 695c2a879fe..6f6e090a2ae 100644 --- a/docs/localization.rst +++ b/docs/localization.rst @@ -51,7 +51,7 @@ It also gets included in the Read the Docs flyout: .. note:: The default language of a custom domain is determined by the language of the parent project that the domain was configured on. See - :doc:`alternate_domains` for more information. + :doc:`custom_domains` for more information. .. note:: You can include multiple translations in the same repository, with same ``conf.py`` and ``.rst`` files, diff --git a/docs/single_version.rst b/docs/single_version.rst index d0d526e6ebe..32944000e01 100644 --- a/docs/single_version.rst +++ b/docs/single_version.rst @@ -23,6 +23,6 @@ if pip was set as a "Single Version" project, then links to its documentation wo ``http://pip.readthedocs.io/`` rather than the default ``http://pip.readthedocs.io/en/latest/``. Documentation at ``///`` will still be served for backwards compatibility reasons. -However, our usage of :doc:`canonical` should stop these from being indexed by Google. +However, our usage of :doc:`guides/canonical` should stop these from being indexed by Google. .. _dashboard: https://readthedocs.org/dashboard/