diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 4872be053df..3364b0b74f0 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,4 +1,6 @@ [rstcheck] ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post ignore_roles=djangosetting,setting,featureflags,buildpyversions -ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced) +# This error needs to be ignored for now +# See: https://github.com/myint/rstcheck/issues/19 +ignore_messages=(Hyperlink target ".*" is not referenced) diff --git a/docs/Makefile b/docs/Makefile index 83b49c4db29..7e97a2c7183 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,11 +2,14 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W --keep-going SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build +# Do not use local Django settings during the docs build +export DJANGO_SETTINGS_SKIP_LOCAL = True + # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) diff --git a/docs/advertising/ad-customization.rst b/docs/advertising/ad-customization.rst index 683745723ff..323bcb9047d 100644 --- a/docs/advertising/ad-customization.rst +++ b/docs/advertising/ad-customization.rst @@ -1,3 +1,5 @@ +:orphan: + Customizing Advertising ======================= diff --git a/docs/advertising/advertising-details.rst b/docs/advertising/advertising-details.rst index 51055cc2663..8fc0e358a1f 100644 --- a/docs/advertising/advertising-details.rst +++ b/docs/advertising/advertising-details.rst @@ -97,7 +97,8 @@ Currently we show ads on: * Sphinx theme provided by Read the Docs * MkDocs theme provided by Read the Docs (beginning in May 2018) * Alabaster Sphinx theme -* [Pylons Sphinx Themes](https://github.com/Pylons/pylons-sphinx-themes), including pyramid, pylons, and pylonsfw. +* `Pylons Sphinx Themes `_, + including pyramid, pylons, and pylonsfw. This list will expand as we strive to put advertising on a larger percentage of the documentation served by us. @@ -105,8 +106,6 @@ However, we always give advance notice in our issue tracker and via email about showing ads where none were shown before. -.. _advertising-details-do-not-track: - Do Not Track Policy ------------------- @@ -115,8 +114,6 @@ For more details, see the :ref:`Do Not Track section `. 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/custom_installs/local_rtd_vm.rst b/docs/custom_installs/local_rtd_vm.rst index 23d96433f52..ffc6a6c1c76 100644 --- a/docs/custom_installs/local_rtd_vm.rst +++ b/docs/custom_installs/local_rtd_vm.rst @@ -47,8 +47,8 @@ To host your documentation on a local RTD installation, set it up in your VM: cd readthedocs.org sudo pip install -r requirements.txt -Possible Error and Resolution -````````````````````````````` +Possible errors with a local RTD setup +`````````````````````````````````````` **Error**: ``error: command 'gcc' failed with exit status 1`` @@ -116,8 +116,8 @@ Go to the dashboard at ``http://[VM IP ADDRESS]:8000/dashboard`` and follow the This generates the HTML documentation site using the default Sphinx theme. Verify the output in your local documentation folder under ``../build/html`` -Possible Error and Resolution -````````````````````````````` +Possible errors administering a RTD server +`````````````````````````````````````````` **Error**: Couldn't access Git Corp from VM. @@ -136,9 +136,9 @@ Possible Error and Resolution 3. Now, SSH to the VM. 4. Open the ``id_rsa`` file in the VM: -.. prompt:: bash $ + .. prompt:: bash $ - vim /home//.ssh/id_rsa + vim /home//.ssh/id_rsa 5. Paste the RSA key copied from your machine and save file (``Esc``. ``:wq!``). 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/development/search.rst b/docs/development/search.rst index d07862a5fbc..69cbad062e6 100644 --- a/docs/development/search.rst +++ b/docs/development/search.rst @@ -78,10 +78,11 @@ We also index project information in our search index so that the user can searc from the main site. We listen to the `post_create` and `post_delete` signals of `Project` model and index/delete into Elasticsearch accordingly. + Elasticsearch Document ~~~~~~~~~~~~~~~~~~~~~~ -`elasticsearch-dsl`_ provides model-like wrapper for the `Elasticsearch document`_. +`elasticsearch-dsl`_ provides a model-like wrapper for `the Elasticsearch document`_. As per requirements of `django-elasticsearch-dsl`_, it is stored in the `readthedocs/search/documents.py` file. @@ -103,7 +104,7 @@ As per requirements of `django-elasticsearch-dsl`_, it is stored in the .. _Elasticsearch: https://www.elastic.co/products/elasticsearch .. _Elasticsearch 6.3: https://www.elastic.co/guide/en/elasticsearch/reference/6.3/index.html .. _GitHub Repository: https://github.com/rtfd/readthedocs.org/tree/master/readthedocs/search -.. _Elasticsearch document: https://www.elastic.co/guide/en/elasticsearch/guide/current/document.html +.. _the Elasticsearch document: https://www.elastic.co/guide/en/elasticsearch/guide/current/document.html .. _django-elasticsearch-dsl: https://github.com/sabricot/django-elasticsearch-dsl .. _elasticsearch-dsl: http://elasticsearch-dsl.readthedocs.io/en/latest/ .. _signals: https://docs.djangoproject.com/en/2.1/topics/signals/ 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 83% rename from docs/tests.rst rename to docs/development/tests.rst index 45dc8db568d..59223e5e3a9 100644 --- a/docs/tests.rst +++ b/docs/development/tests.rst @@ -31,17 +31,17 @@ To target a specific environment:: tox -e py36 The ``tox`` configuration has the following environments configured. You can -target a single environment to limit the test suite:: +target a single environment to limit the test suite: - py36 - Run our test suite using Python 3.6 +py36 + Run our test suite using Python 3.6 - lint - Run code linting using `Prospector`_. This currently runs `pylint`_, - `pyflakes`_, `pep8`_ and other linting tools. +lint + Run code linting using `Prospector`_. This currently runs `pylint`_, + `pyflakes`_, `pep8`_ and other linting tools. - docs - Test documentation compilation with Sphinx. +docs + Test documentation compilation with Sphinx. .. _`Tox`: http://tox.readthedocs.io/en/latest/index.html .. _`Prospector`: http://prospector.readthedocs.io/en/master/ 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/guides/manage-translations.rst b/docs/guides/manage-translations.rst index d4d2db8767f..3e0c83733b7 100644 --- a/docs/guides/manage-translations.rst +++ b/docs/guides/manage-translations.rst @@ -38,8 +38,13 @@ To generate these ``.pot`` files it's needed to run this command from your ``doc .. tip:: - We recommend configuring Sphinx to use :ref:`gettext_uuid ` as ``True`` - and also :ref:`gettext_compact ` as ``False`` to generate ``.pot`` files. + We recommend configuring Sphinx to use gettext_uuid_ as ``True`` + and also gettext_compact_ as ``False`` to generate ``.pot`` files. + + .. Unfortunately these are custom types and can't yet be used with intersphinx + .. https://github.com/sphinx-doc/sphinx/issues/5562 + .. _gettext_uuid: https://www.sphinx-doc.org/en/latest/usage/configuration.html#confval-gettext_uuid + .. _gettext_compact: https://www.sphinx-doc.org/en/latest/usage/configuration.html#confval-gettext_compact This command will leave the generated files under ``_build/gettext``. diff --git a/docs/guides/pdf-non-ascii-languages.rst b/docs/guides/pdf-non-ascii-languages.rst index 0c18b277a42..621c12248ee 100644 --- a/docs/guides/pdf-non-ascii-languages.rst +++ b/docs/guides/pdf-non-ascii-languages.rst @@ -1,8 +1,6 @@ Build PDF format for non-ASCII languages ======================================== -.. _open an issue: https://github.com/rtfd/readthedocs.org/issues/new - Sphinx offers different `LaTeX engines`_ that support Unicode characters and non-ASCII languages, like Japanese or Chinese. By default Sphinx uses ``pdflatex``, diff --git a/docs/features/sitemaps.rst b/docs/guides/sitemaps.rst similarity index 90% rename from docs/features/sitemaps.rst rename to docs/guides/sitemaps.rst index cc22242e220..871fdcb5b6c 100644 --- a/docs/features/sitemaps.rst +++ b/docs/guides/sitemaps.rst @@ -1,5 +1,5 @@ -Sitemaps -======== +Sitemaps: An SEO tool for documentation +======================================= Sitemaps_ allows us to inform search engines about URLs that are available for crawling and communicate them additional information about each URL of the project: 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/privacy-policy.rst b/docs/privacy-policy.rst index c47fcef5b20..8cf2c9e43a4 100644 --- a/docs/privacy-policy.rst +++ b/docs/privacy-policy.rst @@ -92,8 +92,8 @@ User Personal Information does not include aggregated, non-personally identifyin We may use aggregated, non-personally identifying information to operate, improve, and optimize our website and service. -Why do we collect this? -+++++++++++++++++++++++ +Why do we collect this information? ++++++++++++++++++++++++++++++++++++ - We need your User Personal Information to create your account, and to provide the services you request. - We use your User Personal Information, specifically your user name, to identify you on Read the Docs. 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/ diff --git a/docs/sponsors.rst b/docs/sponsors.rst index 2286a4ba1f2..8432d6f8003 100644 --- a/docs/sponsors.rst +++ b/docs/sponsors.rst @@ -25,7 +25,6 @@ Past sponsors * `Rackspace`_ * `Mozilla`_ -.. _MOSS grant: https://blog.readthedocs.com/rtd-awarded-mozilla-open-source-support-grant/ .. _Revsys: http://www.revsys.com/ .. _Python Software Foundation: http://python.org/psf/ .. _Mozilla Web Dev: http://blog.mozilla.com/webdev/ diff --git a/docs/team.rst b/docs/team.rst index eaf3f21608f..c25e30dc652 100644 --- a/docs/team.rst +++ b/docs/team.rst @@ -29,18 +29,18 @@ This might include tasks like: * Asking for a project name to be released * Troubleshooting build errors -Members -~~~~~~~ +Support team members +~~~~~~~~~~~~~~~~~~~~ -* `Eric Holscher `__ (Pacific Time) -* `Anthony Johnson `__ (Mountain Time) -* `Manuel Kaufmann `__ (Central Time) +* `Eric Holscher`_ (Pacific Time) +* `Anthony Johnson`_ (Mountain Time) +* `Manuel Kaufmann`_ (Central Time) * Your Name Here **Please don't email us personally for support on Read the Docs.** You can email support@readthedocs.org for any issues you may have. -Joining -~~~~~~~ +Joining the support team +~~~~~~~~~~~~~~~~~~~~~~~~ The best place to start would be to start addressing some of the issues in our issue tracker. We have our support policies quite well documented in our :doc:`/contribute`. @@ -59,18 +59,18 @@ As part of operating the site, we maintain a 24/7 on-call rotation. This means that folks have to be available and have their phone in service. -Members -~~~~~~~ +Ops team members +~~~~~~~~~~~~~~~~ -* `Eric Holscher `_ (Pacific Time) -* `Anthony Johnson `_ (Mountain Time) -* `Matt Robenolt `_ (Pacific Time) +* `Eric Holscher`_ (Pacific Time) +* `Anthony Johnson`_ (Mountain Time) +* `Matt Robenolt`_ (Pacific Time) * Your Name Here Feel free to ask any of us if you have questions or want to join! -Joining -~~~~~~~ +Joining the ops team +~~~~~~~~~~~~~~~~~~~~ We are always looking for more people to share the on-call responsibility. If you are on-call for your job already, @@ -103,20 +103,20 @@ Development Team Also known as the "Core Team" in other projects. These folks have the ability to commit code to the project. -Members -~~~~~~~ +Dev team members +~~~~~~~~~~~~~~~~ -* `Eric Holscher `_ -* `Anthony Johnson `_ -* `Manuel Kaufmann `_ -* `David Fischer `_ -* `Santos Gallegos `_ +* `Eric Holscher`_ +* `Anthony Johnson`_ +* `Manuel Kaufmann`_ +* `David Fischer`_ +* `Santos Gallegos`_ * Your name here Feel free to ask any of us if you have questions or want to join! -Joining -~~~~~~~ +Joining the dev team +~~~~~~~~~~~~~~~~~~~~ We try to be pretty flexible with who we allow on the development team. The best path is to send a few pull requests, @@ -125,3 +125,11 @@ You can check out our :doc:`contribute` to get more information, and find issues that need to be addressed. After that, feel free to ask for a commit bit. + + +.. _Eric Holscher: https://github.com/ericholscher +.. _Anthony Johnson: https://github.com/agjohnson +.. _Manuel Kaufmann: https://github.com/humitos +.. _David Fischer: https://github.com/davidfischer +.. _Santos Gallegos: https://github.com/stsewd +.. _Matt Robenolt: https://github.com/mattrobenolt diff --git a/tox.ini b/tox.ini index ffac6f78c68..c6179efc1fc 100644 --- a/tox.ini +++ b/tox.ini @@ -25,7 +25,7 @@ commands = description = build readthedocs documentation changedir = {toxinidir}/docs commands = - sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html + sphinx-build -W --keep-going -b html -d {envtmpdir}/doctrees . {envtmpdir}/html [testenv:migrations] description = check for missing migrations