diff --git a/common b/common index bac30e0debe..042949ff113 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit bac30e0debe92ac2d60607bddb8e0dc83718f24b +Subproject commit 042949ff11321a9d044efdf41b0620089aac1981 diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index bb043a9f0b7..658a5491725 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,6 +1,7 @@ [rstcheck] ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete ignore_roles=djangosetting,setting,featureflags,buildpyversions +ignore_substitutions=org_brand,com_brand # 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/_ext/djangodocs.py b/docs/_ext/djangodocs.py index 2551233aaaa..3880d9f5649 100644 --- a/docs/_ext/djangodocs.py +++ b/docs/_ext/djangodocs.py @@ -4,3 +4,9 @@ def setup(app): rolename="setting", indextemplate="pair: %s; setting", ) + + return { + 'version': 'builtin', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/docs/_static/images/guides/search-analytics-demo.png b/docs/_static/images/guides/search-analytics-demo.png deleted file mode 100644 index 81269a7171e..00000000000 Binary files a/docs/_static/images/guides/search-analytics-demo.png and /dev/null differ diff --git a/docs/_static/images/search-analytics-demo.png b/docs/_static/images/search-analytics-demo.png new file mode 100644 index 00000000000..048849460b0 Binary files /dev/null and b/docs/_static/images/search-analytics-demo.png differ diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 00000000000..38b25874ff4 --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,27 @@ +About Read the Docs +=================== + +Read the Docs is a C Corporation registered in Oregon. +Our bootstrapped company is owned and fully controlled by the founders, +and fully funded by our customers and advertisers. +This allows us to **focus 100% on our users**. + +We have two main sources of revenue: + +* |com_brand| - where we `provide `__ a valuable paid service to companies. +* |org_brand| - where we provide a free service to the open source community, funded via :doc:`/advertising/ethical-advertising`. + +We believe that having both paying customers and ethical advertising is the best way to create a sustainable platform for our users. +We have built something that we expect to last a long time, +and we are able to make decisions based only on the best interest of our community and customers. + +All of the source code for Read the Docs is open source. +You are welcome to :doc:`contribute ` the features you want or run your own instance. +We should note that we generally only support our hosted versions as a matter of :doc:`our philosophy `. + +We owe a great deal to the open source community that we are a part of, +so we provide free ads via our :ref:`community ads ` program. +This allows us to give back to the communities and projects that we support and depend on. + +We are proud about the way we manage our company and products, +and are glad to have you on board with us in this :doc:`great documentation journey `. diff --git a/docs/automatic-redirects.rst b/docs/automatic-redirects.rst index 2e6e97dfbd7..8f286361bb9 100644 --- a/docs/automatic-redirects.rst +++ b/docs/automatic-redirects.rst @@ -4,6 +4,19 @@ Automatic Redirects Read the Docs supports redirecting certain URLs automatically. This is an overview of the set of redirects that are fully supported and will work into the future. +Redirecting to a Page +--------------------- + +You can link to a specific page and have it redirect to your default version. +This is done with the ``/page/`` URL prefix. +You can reach this page by going to https://docs.readthedocs.io/page/automatic-redirects.html. + +This allows you to create links that are always up to date. + +Another way to handle this is the ``latest`` version. +You can set your ``latest`` version to a specific version and just always link to ``latest``. +You can read more about this in our :doc:`versions ` page. + Root URL -------- @@ -11,8 +24,8 @@ A link to the root of your documentation will redirect to the *default version*, as set in your project settings. For example:: - pip.readthedocs.io -> pip.readthedocs.io/en/latest/ - www.pip-installer.org -> www.pip-installer.org/en/latest + docs.readthedocs.io -> docs.readthedocs.io/en/latest/ + www.pip-installer.org -> www.pip-installer.org/en/latest/ This only works for the root URL, not for internal pages. It's designed to redirect people from http://pip.readthedocs.io/ to the default version of your documentation, since serving up a 404 here would be a pretty terrible user experience. (If your "develop" branch was designated as your default version, then it would redirect to http://pip.readthedocs.io/en/develop.) But, it's not a universal redirecting solution. So, for example, a link to an internal page like http://pip.readthedocs.io/usage.html doesn't redirect to http://pip.readthedocs.io/en/latest/usage.html. @@ -20,13 +33,15 @@ The reasoning behind this is that RTD organizes the URLs for docs so that multip Among all the multiple versions of docs, you can choose which is the "default" version for RTD to display, which usually corresponds to the git branch of the most recent official release from your project. -rtfd.org +rtfd.io ~~~~~~~~ -Links to rtfd.org are treated the same way as above. +Links to rtfd.io are treated the same way as above. They redirect the root URL to the default version of the project. They are intended to be easy and short for people to type. +You can reach these docs at https://docs.rtfd.io. + Supported Top-Level Redirects ----------------------------- @@ -43,19 +58,3 @@ The main challenge of URL routing in Read the Docs is handling redirects correct The language redirect will work for any of the defined ``LANGUAGE_CODES`` we support. The version redirect will work for supported versions. - -Redirecting to a Page ---------------------- - -You can link to a specific page and have it redirect to your default version. -This is done with the ``/page/`` URL. -For example:: - - pip.readthedocs.io/page/quickstart.html -> pip.readthedocs.io/en/latest/quickstart.html - www.pip-installer.org/page/quickstart.html -> www.pip-installer.org/en/latest/quickstart.html - -This allows you to create links that are always up to date. - -Another way to handle this is the *latest* version. -You can set your ``latest`` version to a specific version and just always link to latest. - diff --git a/docs/builds.rst b/docs/builds.rst index 214fa689caa..2236b39e9d1 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -4,62 +4,29 @@ Build Process Every documentation build has limited resources. Our current build limits are: -* 15 minutes of CPU -* 3GB of RAM memory -* 2 concurrent builds +.. tabs:: -We can increase build limits on a per-project basis, -sending an email to support@readthedocs.org providing a good reason why your documentation needs more resources. -If your business is hitting build limits hosting documentation on Read the Docs, -please consider :doc:`Read the Docs for Business ` -which has much higher build resources. + .. tab:: |org_brand| -You can see the current Docker build images that we use in our `docker repository `_. -`Docker Hub `_ also shows the latest set of images that have been built. - -Currently in production we're using the ``readthedocs/build:latest`` docker image as our default image. - -How we build documentation --------------------------- - -When we import your documentation, we look at two things first: your *Repository URL* and the *Documentation Type*. -We will clone your repository, -and then build your documentation using the *Documentation Type* specified. - -Sphinx -~~~~~~ + * 15 minutes build time + * 3GB of memory + * 2 concurrent builds -When you choose *Sphinx* as your *Documentation Type*, -we will first look for a ``conf.py`` file in your repository. -If we don't find one, -we will generate one for you. -We will look inside a ``doc`` or ``docs`` directory first, -and then look within your entire project. + We can increase build limits on a per-project basis. + Send an email to support@readthedocs.org providing a good reason why your documentation needs more resources. -Then Sphinx will build any files with an ``.rst`` extension. + If your business is hitting build limits hosting documentation on Read the Docs, + please consider :doc:`Read the Docs for Business ` + which has much higher build resources. -MkDocs -~~~~~~ + .. tab:: |com_brand| -When you choose *Mkdocs* as your *Documentation Type*, -we will first look for a ``mkdocs.yml`` file in the root of your repository. -If we don't find one, -we will generate one for you. - -Then MkDocs will build any files with a ``.md`` extension within the directory specified as ``docs_dir`` in the ``mkdocs.yml``. - -If no ``mkdocs.yml`` was found in the root of your repository and we generated one for you, -Read the Docs will attempt to set ``docs_dir`` by sequentially searching for a ``docs``, ``doc``, ``Doc``, or ``book`` directory. -The first of these directories that exists and contains files with a ``.md`` extension will be set to ``docs_dir`` within ``mkdocs.yml``, -and MkDocs will build the ``.md`` files in that directory. -As MkDocs doesn't support automatic PDF generation, -Read the Docs cannot create a PDF version of your documentation with the *Mkdocs* option. - -.. warning:: - - We strongly recommend to :ref:`pin the MkDocs version ` - used for your project to build the docs to avoid potential future incompatibilities. + * 30 minutes build time + * 7GB of memory + * 4 concurrent builds + If you are having trouble with your documentation builds, + you can reach our support at support@readthedocs.com. Understanding what's going on ----------------------------- @@ -70,19 +37,19 @@ It should also allow you to take advantage of certain things that happen during The first step of the process is that we check out your code from the repository you have given us. If the code is already checked out, we update the copy to the branch that you have specified in your project's configuration. -Then we build the proper backend code for the type of documentation you've selected. +Then we build the proper backend code for the type of documentation you've selected, +this is done inside a :ref:`Docker container `. At this point, if you need extra requirements, or even install your own package in the virtual environment to build your documentation, you can use a :doc:`config-file/index`. -When we build your Sphinx documentation, we run ``sphinx-build -b html . _build/html``, -where ``html`` would be replaced with the correct backend. +When we build your Sphinx documentation, we run ``sphinx-build -b . _build/`` We also create pdf's and ePub's automatically based on your project. For MkDocs, we run ``mkdocs build``. -Then these files are copied across to our application servers from the build server. -Once on the application servers, they are served from nginx. +Once these files are built, +they are deployed to our file hosting backend and will be visible to users. An example in code: @@ -90,15 +57,12 @@ An example in code: update_docs_from_vcs(version) config = get_config(project) - if config.python.install.method.setuptools: - run('python setup.py install') if config.python.install.method.pip: run('pip install .') if config.python.install.requirement: run('pip install -r %s' % config.python.install.requirement) - build_docs(version=version) - copy_files(artifact_dir) - + build_docs(version) + deploy_docs(version) .. note:: @@ -108,79 +72,36 @@ An example in code: :doc:`dependencies are specified `. Some examples of pinning versions might be ``sphinx<2.0`` or ``mkdocs>=1.0``. -Builder responsibility ----------------------- - -Builders have a very specific job. -They take the updated source code and generate the correct artifacts. -The code lives in ``self.version.project.checkout_path(self.version.slug)``. -The artifacts should end up in ``self.version.project.artifact_path(version=self.version.slug, type=self.type)`` -Where ``type`` is the name of your builder. -All files that end up in the artifact directory should be in their final form. - -The build environment ---------------------- - -The build process is executed inside Docker containers, -by default the image used is ``readthedocs/build:latest``, -but you can change that using a :doc:`config-file/index`. - -.. note:: - - The Docker images have a select number of C libraries installed, - because they are used across a wide array of python projects. - We can't install every C library out there, - but we try and support the major ones. - -.. tip:: - - If you want to know the specific version of a package that is installed in the image - you can check the `Ubuntu package search page `__. - -More details on software installed in images could be found by browsing specific branch in `rtfd/readthedocs-docker-images `__ repository. - -Writing your own builder ------------------------- - -.. note:: Builds happen on a server using only the RTD Public API. There is no reason that you couldn't build your own independent builder that wrote into the RTD namespace. The only thing that is currently unsupported there is a saner way than uploading the processed files as a zip. - -The documentation build system in RTD is made pluggable, so that you can build out your own backend. If you have a documentation format that isn't currently supported, you can add support by contributing a backend. - -`The builder backends`_ detail the higher level parts of the API that you need to implement. A basic run goes something like this: - -.. sourcecode:: python - - backend = get_backend(project.documentation_type) - if force: - backend.force(version) - backend.clean(version) - backend.build(version) - if success: - backend.move(version) - -.. _The builder backends: https://github.com/readthedocs/readthedocs.org/tree/master/readthedocs/doc_builder/backends - -Deleting a stale or broken build environment --------------------------------------------- - -If you're having trouble getting your version to build, try wiping out the existing build/environment files. On your version list page ``/projects/[project]/versions`` there is a "Wipe" button that will remove all of the files associated with your documentation build, but not the documentation itself. - Build environment ----------------- The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment variables when building your documentation: -.. csv-table:: - :header-rows: 1 +.. csv-table:: Environment Variables + :header: Environment variable, Description, Example value + :widths: 15, 10, 30 + + ``READTHEDOCS``, Whether the build is running inside RTD, ``True`` + ``READTHEDOCS_VERSION``, The RTD name of the version which is being built, ``latest`` + ``READTHEDOCS_PROJECT``, The RTD slug of the project which is being built, ``my-example-project`` + ``READTHEDOCS_LANGUAGE``, The RTD language slug of the project which is being built, ``en`` - Environment variable, Description, Example value - ``READTHEDOCS``, Whether the build is running inside RTD, ``True`` - ``READTHEDOCS_VERSION``, The RTD name of the version which is being built, ``latest`` - ``READTHEDOCS_PROJECT``, The RTD slug of the project which is being built, ``my-example-project`` - ``READTHEDOCS_LANGUAGE``, The RTD language slug of the project which is being built, ``en`` +If you want to learn more about how the build environment works as a low level, +you can read about it in our :doc:`/development/buildenvironments` docs. .. tip:: In case extra environment variables are needed to the build process (like secrets, tokens, etc), you can add them going to :guilabel:`Admin` > :guilabel:`Environment Variables` in your project. See :doc:`guides/environment-variables`. + + +Docker images +------------- + +The build process is executed inside Docker containers, +by default the image used is ``readthedocs/build:latest``, +but you can change that using a :doc:`/config-file/index`. + +You can see the current Docker build images that we use in our `docker repository `_. +`Docker Hub `_ also shows the latest set of images that have been built. diff --git a/docs/conf.py b/docs/conf.py index 3c8817938da..43894bb9ea2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,6 +36,7 @@ def get_version(): 'notfound.extension', 'hoverxref.extension', 'sphinx_search.extension', + 'sphinxemoji.sphinxemoji', ] templates_path = ['_templates'] @@ -101,6 +102,10 @@ def get_version(): 'confval': 'tooltip', # for custom object } +rst_epilog = """ +.. |org_brand| replace:: Read the Docs Community +.. |com_brand| replace:: Read the Docs for Business +""" # Activate autosectionlabel plugin autosectionlabel_prefix_document = True @@ -132,4 +137,4 @@ def get_version(): def setup(app): - app.add_stylesheet('css/sphinx_prompt_css.css') + app.add_css_file('css/sphinx_prompt_css.css') diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index fabf9bdd580..cddcc56598d 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -3,7 +3,7 @@ Configuration File In addition to using the admin panel of your project to configure your project, you can use a configuration file in the root of your project. -The configuration file can be named as: +The configuration file can be named: - ``readthedocs.yml`` - ``readthedocs.yaml`` @@ -12,10 +12,10 @@ The configuration file can be named as: The main advantages of using a configuration file over the web interface are: +- Settings are per version rather than per project. +- Settings live in your VCS. +- They enable reproducible build environments over time. - Some settings are only available using a configuration file -- The settings are per version rather than per project. -- The settings live in your VCS. -- Reproducible build environments over time. .. tip:: diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index fc6fabbaab1..c80a65d9783 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -1,7 +1,7 @@ -Configuration File V1 -===================== +Configuration File V1 (Deprecated) +================================== -Read the Docs now has support for configuring builds with a YAML file. +Read the Docs has support for configuring builds with a YAML file. :doc:`The Read the Docs file ` must be in the root directory of your project. .. warning:: @@ -167,7 +167,7 @@ python.use_system_site_packages When true, it gives the virtual environment access to the global site-packages directory. Depending on the :ref:`config-file/v1:build.image`, Read the Docs includes some libraries like scipy, numpy, etc. -See :ref:`builds:The build environment` for more details. +See :doc:`/builds` for more details. .. code-block:: yaml diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 759e67b477f..88f5d3a73b4 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -2,9 +2,10 @@ Configuration File V2 ===================== Read the Docs supports configuring your documentation builds with a YAML file. -:doc:`The Read the Docs file ` must be in the root directory of your project. +The :doc:`configuration file ` must be in the root directory of your project. +We recommend the filename ``.readthedocs.yml``. -Below is an example YAML file which may require some changes for your project's configuration: +Below is an example YAML file which shows the most common configuration options: .. code:: yaml @@ -23,8 +24,9 @@ Below is an example YAML file which may require some changes for your project's #mkdocs: # configuration: mkdocs.yml - # Optionally build your docs in additional formats such as PDF and ePub - formats: all + # Optionally build your docs in additional formats such as PDF + formats: + - pdf # Optionally set the version of Python and requirements required to build your docs python: @@ -36,10 +38,13 @@ Below is an example YAML file which may require some changes for your project's Supported settings ------------------ -.. note:: +Read the Docs validates every configuration file. +Any configuration option that isn't supported will make the build fail. +This is to avoid typos and provide feedback on invalid configurations. - The presence of any other key that isn't documented here will make the build to fail. - This is to avoid typos and provide feedback on invalid configurations. +.. contents:: + :local: + :depth: 1 version ~~~~~~~ @@ -88,15 +93,14 @@ Example: # Build all formats formats: all -.. note:: +.. warning:: - PDF/epub/htmlzip output is not supported when using MkDocs + ``pdf``, ``epub``, and ``htmlzip`` output is not supported when using MkDocs. python ~~~~~~ Configuration of the Python environment to be used. -Example: .. code-block:: yaml @@ -223,7 +227,7 @@ Give the virtual environment access to the global site-packages directory. Depending on the :ref:`config-file/v2:build.image`, Read the Docs includes some libraries like scipy, numpy, etc. That you can access to them by enabling this option. -See :ref:`builds:The build environment` for more details. +See :doc:`/builds` for more details. .. warning:: @@ -235,7 +239,6 @@ conda ~~~~~ Configuration for Conda support. -Example: .. code-block:: yaml @@ -254,7 +257,6 @@ build ~~~~~ Configuration for the documentation build process. -Example: .. code-block:: yaml @@ -285,7 +287,6 @@ sphinx Configuration for Sphinx documentation (this is the default documentation type). -Example: .. code-block:: yaml @@ -331,7 +332,6 @@ mkdocs ~~~~~~ Configuration for Mkdocs documentation. -Example: .. code-block:: yaml @@ -368,12 +368,10 @@ VCS submodules configuration. Only Git is supported at the moment. -.. note:: +.. warning:: You can't use ``include`` and ``exclude`` settings for submodules at the same time. -Example: - .. code-block:: yaml submodules: diff --git a/docs/connected-accounts.rst b/docs/connected-accounts.rst index 3a913b46e42..c25d6dbf76f 100644 --- a/docs/connected-accounts.rst +++ b/docs/connected-accounts.rst @@ -1,5 +1,5 @@ -Connecting Your Account -======================= +Connecting Your VCS Account +=========================== If you are going to import repositories from GitHub, Bitbucket, or GitLab, you should connect your Read the Docs account to your repository host first. diff --git a/docs/custom_domains.rst b/docs/custom_domains.rst index edfc90a8ba6..07966961632 100644 --- a/docs/custom_domains.rst +++ b/docs/custom_domains.rst @@ -1,5 +1,5 @@ -Custom Domains -============== +Custom Domains and White Labeling +================================= Once a project is imported into Read the Docs, by default it's hosted under a subdomain on one of our domains. diff --git a/docs/development/buildenvironments.rst b/docs/development/buildenvironments.rst index 17cc55335fb..6ecb2e55e8b 100644 --- a/docs/development/buildenvironments.rst +++ b/docs/development/buildenvironments.rst @@ -1,4 +1,3 @@ -================== Build Environments ================== @@ -108,3 +107,35 @@ DOCKER_USE_DEV_IMAGES If set to ``True``, replace the normal Docker image name used in building ``readthedocs/build`` with the image name output for these commands, ``readthedocs/build-dev``. + +Builder responsibility +---------------------- + +Builders have a very specific job. +They take the updated source code and generate the correct artifacts. +The code lives in ``self.version.project.checkout_path(self.version.slug)``. +The artifacts should end up in ``self.version.project.artifact_path(version=self.version.slug, type=self.type)`` +Where ``type`` is the name of your builder. +All files that end up in the artifact directory should be in their final form. + + +Writing your own builder +------------------------ + +.. note:: Builds happen on a server using only the RTD Public API. There is no reason that you couldn't build your own independent builder that wrote into the RTD namespace, but that would require work on our side if you can convince us :) + +The documentation build system in RTD is made pluggable, so that you can build out your own backend. If you have a documentation format that isn't currently supported, you can add support by contributing a backend. + +`The builder backends`_ detail the higher level parts of the API that you need to implement. A basic run goes something like this: + +.. sourcecode:: python + + backend = get_backend(project.documentation_type) + if force: + backend.force(version) + backend.clean(version) + backend.build(version) + if success: + backend.move(version) + +.. _The builder backends: https://github.com/readthedocs/readthedocs.org/tree/master/readthedocs/doc_builder/backends diff --git a/docs/downloadable-documentation.rst b/docs/downloadable-documentation.rst new file mode 100644 index 00000000000..2695bd13179 --- /dev/null +++ b/docs/downloadable-documentation.rst @@ -0,0 +1,40 @@ +Downloadable Documentation +========================== + +Read the Docs supports building multiple formats for Sphinx-based projects: + +* PDF +* ePub +* Zipped HTML + +This means that every commit that you push will automatically update your PDFs as well as your HTML. + +This is enabled by the :ref:`config-file/v2:formats` key in our config file. +A simple example is here: + +.. code-block:: yaml + + # Build PDF & ePub + formats: + - epub + - pdf + +If you want to see an example, +you can download the Read the Docs documentation in the following formats: + + * `PDF`_ + * `ePub`_ + * `Zipped HTML`_ + +.. _PDF: https://docs.readthedocs.io/_/downloads/en/latest/pdf/ +.. _ePub: https://docs.readthedocs.io/_/downloads/en/latest/epub/ +.. _Zipped HTML: https://docs.readthedocs.io/_/downloads/en/latest/htmlzip/ + +Use cases +--------- + +This functionality is great for anyone who needs documentation when they aren't connected to the internet. +Users who are about to get on a plane can grab a PDF and have the entire doc set ready for their trip. + +The other value is having the entire docset in a single file. +You can send a user an email with a single PDF or ePub and they'll have all the docs in one place. diff --git a/docs/faq.rst b/docs/faq.rst index f98f22734c9..60302d0d9f6 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,37 +1,17 @@ Frequently Asked Questions ========================== -My project isn't building with autodoc --------------------------------------- +My project isn't building correctly +----------------------------------- -First, you should check out the Builds tab of your project. That records all of the build attempts that RTD has made to build your project. If you see ``ImportError`` messages for custom Python modules, you should enable the virtualenv feature in the Admin page of your project, which will install your project into a virtualenv, and allow you to specify a ``requirements.txt`` file for your project. +First, you should check out the Builds tab of your project. +That records all of the build attempts that RTD has made to build your project. +If you see ``ImportError`` messages for custom Python modules, +see our section on :ref:`faq:My documentation requires additional dependencies`. If you are still seeing errors because of C library dependencies, please see :ref:`faq:I get import errors on libraries that depend on C modules`. -How do I change my project slug (the URL your docs are served at)? ------------------------------------------------------------------- - -We don't support allowing folks to change the slug for their project. -You can update the name which is shown on the site, -but not the actual URL that documentation is served. - -The main reason for this is that all existing URLs to the content will break. -You can delete and re-create the project with the proper name to get a new slug, -but you really shouldn't do this if you have existing inbound links, -as it `breaks the internet `_. - -If that isn't enough, -you can request the change sending an email to support@readthedocs.org. - - -How do I change the version slug of my project? ------------------------------------------------ - -We don't support allowing folks to change the slug for their versions. -But you can rename the branch/tag to achieve this. -If that isn't enough, -you can request the change sending an email to support@readthedocs.org. Help, my build passed but my documentation page is 404 Not Found! ----------------------------------------------------------------- @@ -48,35 +28,31 @@ otherwise we aren't able to serve a "default" index page. To test if your docs actually built correctly, you can navigate to a specific page (`/en/latest/README.html` for example). -How do I change behavior for Read the Docs? -------------------------------------------- -When RTD builds your project, it sets the :envvar:`READTHEDOCS` environment -variable to the string `True`. So within your Sphinx :file:`conf.py` file, you -can vary the behavior based on this. For example:: +My documentation requires additional dependencies +------------------------------------------------- - import os - on_rtd = os.environ.get('READTHEDOCS') == 'True' - if on_rtd: - html_theme = 'default' - else: - html_theme = 'nature' +For most Python dependencies, you can can specify a requirements file +which details your dependencies. See our guide on :doc:`/guides/specifying-dependencies`. +You can also set your project documentation to install your project itself +as a dependency. -The :envvar:`READTHEDOCS` variable is also available in the Sphinx build -environment, and will be set to ``True`` when building on RTD:: +If your project or its dependencies rely on C libraries, +see :ref:`faq:I get import errors on libraries that depend on C modules`. - {% if READTHEDOCS %} - Woo - {% endif %} -My project requires different settings than those available under Admin ------------------------------------------------------------------------ +My project requires some additional settings +-------------------------------------------- + +If this is just a dependency issue, +see :ref:`faq:My documentation requires additional dependencies`. -Read the Docs offers some settings which can be used for a variety of purposes, -such as to use the latest version of sphinx or pip. To enable these settings, +Read the Docs offers some settings which can be used for a variety of purposes. +To enable these settings, please send an email to support@readthedocs.org and we will change the settings for the project. Read more about these settings :doc:`here `. + I get import errors on libraries that depend on C modules --------------------------------------------------------- @@ -93,6 +69,30 @@ If such libraries are installed via ``setup.py``, you also will need to remove a .. _autodoc_mock_imports: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports + +How do I change behavior when building with Read the Docs? +---------------------------------------------------------- + +When RTD builds your project, it sets the :envvar:`READTHEDOCS` environment +variable to the string ``'True'``. So within your Sphinx :file:`conf.py` file, you +can vary the behavior based on this. For example:: + + import os + on_rtd = os.environ.get('READTHEDOCS') == 'True' + if on_rtd: + html_theme = 'default' + else: + html_theme = 'nature' + +The :envvar:`READTHEDOCS` variable is also available in the Sphinx build +environment, and will be set to ``True`` when building on RTD:: + + {% if READTHEDOCS %} + Woo + {% endif %} + + + `Client Error 401` when building documentation ---------------------------------------------- @@ -113,11 +113,13 @@ following settings:: SLUMBER_USERNAME = 'test' SLUMBER_PASSWORD = 'test' + Deleting a stale or broken build environment -------------------------------------------- See :doc:`guides/wipe-environment`. + How do I host multiple projects on one custom domain? ----------------------------------------------------- @@ -137,15 +139,30 @@ http://docs.celeryproject.org/projects/kombu/en/latest/ You can add subprojects in the project admin dashboard. +For details on custom domains, see our documentation on :doc:`/custom_domains`. + + Where do I need to put my docs for RTD to find it? -------------------------------------------------- -Read the Docs will crawl your project looking for a ``conf.py``. Where it finds the ``conf.py``, it will run ``sphinx-build`` in that directory. So as long as you only have one set of sphinx documentation in your project, it should Just Work. +Read the Docs will crawl your project looking for a ``conf.py``. Where it finds the ``conf.py``, +it will run ``sphinx-build`` in that directory. +So as long as you only have one set of sphinx documentation in your project, it should Just Work. + +You can specify an exact path to your documentation using a Read the Docs :doc:`config-file/index`. + I want to use the Blue/Default Sphinx theme ------------------------------------------- -We think that our theme is badass, and better than the default for many reasons. Some people don't like change though :), so there is a hack that will let you keep using the default theme. If you set the ``html_style`` variable in your ``conf.py``, it should default to using the default theme. The value of this doesn't matter, and can be set to ``/default.css`` for default behavior. +We think that our theme is badass, +and better than the default for many reasons. +Some people don't like change though |:smile:|, +so there is a hack that will let you keep using the default theme. +If you set the ``html_style`` variable in your ``conf.py``, +it should default to using the default theme. +The value of this doesn't matter, and can be set to ``/default.css`` for default behavior. + I want to use the Read the Docs theme locally --------------------------------------------- @@ -153,24 +170,29 @@ I want to use the Read the Docs theme locally There is a repository for that: https://github.com/readthedocs/sphinx_rtd_theme. Simply follow the instructions in the README. + Image scaling doesn't work in my documentation ----------------------------------------------- Image scaling in docutils depends on PIL. PIL is installed in the system that RTD runs on. However, if you are using the virtualenv building option, you will likely need to include PIL in your requirements for your project. + I want comments in my docs -------------------------- -RTD doesn't have explicit support for this. That said, a tool like `Disqus`_ (and the `sphinxcontrib-disqus`_ plugin) can be used for this purpose on RTD. +RTD doesn't have explicit support for this. +That said, a tool like `Disqus`_ (and the `sphinxcontrib-disqus`_ plugin) can be used for this purpose on RTD. .. _Disqus: https://disqus.com/ .. _sphinxcontrib-disqus: https://pypi.python.org/pypi/sphinxcontrib-disqus + How do I support multiple languages of documentation? ----------------------------------------------------- See the section on :doc:`localization`. + Does Read The Docs work well with "legible" docstrings? ------------------------------------------------------- @@ -196,6 +218,7 @@ and as a result, it tends to look a bit better with the default theme. To use these extensions you need to specify the dependencies on your project by following this :doc:`guide `. + Can I document a python package that is not at the root of my repository? ------------------------------------------------------------------------- @@ -209,30 +232,24 @@ If you want to place your package in a different directory or have multiple python packages in the same project, then create a pip requirements file. You can specify the relative path to your package inside the file. For example you want to keep your python package in the ``src/python`` -directory, then create a ``requirements.readthedocs.txt`` file with the +directory, then create a ``requirements.txt`` file with the following contents:: src/python/ Please note that the path must be relative to the file. So the example path above would work if the file is in the root of your repository. If you want to -put the requirements in a file called ``requirements/readthedocs.txt``, the +put the requirements in a file called ``requirements/requirements.txt``, the contents would look like:: ../python/ -After adding the file to your repository, go to the *Advanced Settings* in -your project's admin panel and add the name of the file to the *Requirements -file* field. +You can customize the path to your requirements file and any other installed dependency +using a Read the Docs :doc:`config-file/index`. .. _Sphinx's autoapi: http://sphinx-doc.org/ext/autodoc.html .. _pip requirements file: https://pip.pypa.io/en/stable/user_guide.html#requirements-files -What commit of Read the Docs is in production? ----------------------------------------------- - -We deploy readthedocs.org from the `rel` branch in our GitHub repository. You can see the latest commits that have been deployed by looking on GitHub: https://github.com/readthedocs/readthedocs.org/commits/rel - How can I avoid search results having a deprecated version of my docs? ---------------------------------------------------------------------- @@ -243,44 +260,44 @@ and start suggesting the latest (or newer) one. To accomplish this, you can add a ``robots.txt`` file to your documentation's root so it ends up served at the root URL of your project (for example, https://yourproject.readthedocs.io/robots.txt). +We have documented how to set this up in our :ref:`hosting:Custom robots.txt Pages` docs. -Minimal example of ``robots.txt`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Can I remove advertising from my documentation? +----------------------------------------------- -:: +See :ref:`Opting out of advertising `. - User-agent: * - Disallow: /en/deprecated-version/ - Disallow: /en/2.0/ -.. note:: +How do I change my project slug (the URL your docs are served at)? +------------------------------------------------------------------ - See `Google's docs`_ for its full syntax. +We don't support allowing folks to change the slug for their project. +You can update the name which is shown on the site, +but not the actual URL that documentation is served. -This file has to be served as is under ``/robots.txt``. +The main reason for this is that all existing URLs to the content will break. +You can delete and re-create the project with the proper name to get a new slug, +but you really shouldn't do this if you have existing inbound links, +as it `breaks the internet `_. -Setup -~~~~~ +If that isn't enough, +you can request the change sending an email to support@readthedocs.org. -The ``robots.txt`` file will be served from the **default version** of your Project. -This is because the ``robots.txt`` file is served at the top-level of your domain, -so we must choose a version to find the file in. -The **default version** is the best place to look for it. -Sphinx and Mkdocs both have different ways of outputting static files in the build: +How do I change the version slug of my project? +----------------------------------------------- -Sphinx -++++++ +We don't support allowing folks to change the slug for their versions. +But you can rename the branch/tag to achieve this. +If that isn't enough, +you can request the change sending an email to support@readthedocs.org. -Sphinx uses `html_extra_path`_ option to add static files to the output. -You need to create a ``robots.txt`` file and put it under the path defined in ``html_extra_path``. -MkDocs -++++++ +What commit of Read the Docs is in production? +---------------------------------------------- -MkDocs needs the ``robots.txt`` to be at the directory defined at `docs_dir`_ config. +We deploy readthedocs.org from the ``rel`` branch in our GitHub repository. +You can see the latest commits that have been deployed by looking on GitHub: https://github.com/readthedocs/readthedocs.org/commits/rel -.. _Google's docs: https://support.google.com/webmasters/answer/6062608 -.. _html_extra_path: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path -.. _docs_dir: https://www.mkdocs.org/user-guide/configuration/#docs_dir +We also keep an up-to-date :doc:`changelog `. diff --git a/docs/features.rst b/docs/features.rst index 442c20240be..cfdb1b63340 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -1,70 +1,91 @@ Read the Docs features ====================== -This will serve as a list of all of the features that Read the Docs currently has. Some features are important enough to have their own page in the docs, others will simply be listed here. +Read the Docs offers a number of platform features that are possible because we both build and host documentation for you. -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. +Automatic Documentation Deployment +---------------------------------- -More information can be found in :doc:`guides/vcs`. +We integrate with GitHub, BitBucket, and GitLab. +We automatically create webhooks in your repository, +which tell us whenever you push a commit. +We will then build and deploy your docs every time you push a commit. +This enables a workflow that we call *Continuous Documentation*: -Auto-updating -------------- +**Once you set up your Read the Docs project, +your users will always have up-to-date documentation.** -The :doc:`webhooks` page talks about the different ways you can ping RTD to let us know your project has been updated. We have official support for GitHub, Bitbucket and GitLab, and anywhere else we have a generic post-commit hook that allows you to POST to a URL to get your documentation built. +Learn more about :doc:`/webhooks`. -Internationalization --------------------- +Custom Domains & White Labeling +------------------------------- -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. +When you import a project to Read the Docs, +we assign you a URL based on your project name. +You are welcome to use this URL, +but we also fully support custom domains for all our documentation projects. -Canonical URLs --------------- +Learn more about :doc:`/custom_domains`. -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. +Versioned Documentation +----------------------- -More information can be found in the :doc:`guides/canonical` page. +We support multiple versions of your documentation, +so that users can find the exact docs for the version they are using. +We build this on top of the version control system that you're already using. +Each version on Read the Docs is just a tag or branch in your repository. -Versions --------- +You don't need to change how you version your code, +we work with whatever process you are already using. +If you don't have a process, +we can recommend one. -We can build multiple versions of your documentation. Look on the "Versions" page -of your project's admin (using the nav on the left) to find a list of available versions -that we've inferred from the tags and branches in your source control system (according to -the support matrix below). On the Versions page you can tell us which versions you'd like us -to build docs for, whether each should be public, protected, or private, and what the default -version should be (we'll redirect there when someone hits your main project page, e.g., -http://my-project.rtfd.org/). +Learn more about :doc:`/versions`. -Version Control Support Matrix -------------------------------- +Downloadable Documentation +-------------------------- + +Read the Docs supports building multiple formats for Sphinx-based projects: + +* PDF +* ePub +* Zipped HTML + +This means that every commit that you push will automatically update your PDFs as well as your HTML. + +This feature is great for users who are about to get on a plane and want offline docs, +as well as being able to ship your entire set of documentation as one file. + +Learn more about :doc:`/downloadable-documentation`. + +Full-Text Search +---------------- -+------------+------------+-----------+------------+-----------+ -| | Git | hg | bzr | svn | -+============+============+===========+============+===========+ -| Tags | Yes | Yes | Yes | No | -+------------+------------+-----------+------------+-----------+ -| Branches | Yes | Yes | Yes | No | -+------------+------------+-----------+------------+-----------+ -| Default | master | default | | trunk | -+------------+------------+-----------+------------+-----------+ +We provide search across all the projects that we host. +This actually comes in two different search experiences: +dashboard search on the Read the Docs dashboard and in-doc search on documentation sites, using your own theme and our search results. +We offer a number of search features: -PDF Generation --------------- +* Search across :doc:`subprojects ` +* Search results land on the exact content you were looking for +* Search across projects you have access to (available on |com_brand|) +* A full range of :doc:`search operators ` including exact matching and excluding phrases. -When you build your project on RTD, we automatically build a PDF of your project's documentation. We also build them for every version that you upload, so we can host the PDFs of your latest documentation, as well as your latest stable releases as well. +Learn more about :doc:`/server-side-search`. -Search ------- +Open Source and Customer Focused +-------------------------------- -We provide full-text search across all of the pages of documentation hosted on our site. This uses Elasticsearch as the search backend. We hope to be integrating this into the site more fully in the future. +Read the Docs cares deeply about our customers and our community. +As part of that commitment, +all of the source code for Read the Docs is open source. +This means there's no vendor lock-in, +and you are welcome to :doc:`contribute ` the features you want or run your own instance. -Alternate Domains ------------------ +Our bootstrapped company is owned and controlled by the founders, +and fully funded by our customers and advertisers. +That allows us to focus 100% of our attention on building the best possible product for you. -We provide support for custom domains, subdomains, and a shorturl for your -project as well. This is outlined in the :doc:`custom_domains` section. +Learn more :doc:`/about`. diff --git a/docs/guides/commercial.rst b/docs/guides/commercial.rst new file mode 100644 index 00000000000..e7415f9d63d --- /dev/null +++ b/docs/guides/commercial.rst @@ -0,0 +1,10 @@ +Read the Docs for Business Guides +--------------------------------- + +These guides are specific to :doc:`/commercial/index`. + +.. toctree:: + :maxdepth: 1 + + private-python-packages + private-submodules diff --git a/docs/guides/custom-404-page.rst b/docs/guides/custom-404-page.rst deleted file mode 100644 index 19a0e3c42fa..00000000000 --- a/docs/guides/custom-404-page.rst +++ /dev/null @@ -1,27 +0,0 @@ -Use a Custom ``404 Not Found`` Page on my Project -================================================= - -If you want your project to use a custom page for not found pages instead of the "Maze Found" default one, -you can put a ``404.html`` at the top level of your project's HTML output. - -When a 404 is returned, Read the Docs checks if there is a ``404.html`` in the root of your project's output and uses it if it exists. - -As the ``404.html`` will be returned for all the URLs where the real page was not found, -all its resources URLs and links must be absolute (starting with a ``/``), -otherwise they will not work when a user clicks on them. - -In case you don't want to deal with these links manually, -or you want to use the same style as your theme, -you can use the `sphinx-notfound-page`_ extension. - - -Using ``sphinx-notfound-page`` extension ----------------------------------------- - -The ``sphinx-notfound-page`` extension automatically creates the proper URLs for your 404 page. -Once the extension is installed, it will generate the default 404 page for your project. -See its documentation_ for how to install and custom it. - - -.. _sphinx-notfound-page: https://pypi.org/project/sphinx-notfound-page -.. _documentation: https://sphinx-notfound-page.readthedocs.io/ diff --git a/docs/guides/hiding-a-version.rst b/docs/guides/hiding-a-version.rst index fa6403f1037..9c3873a29c1 100644 --- a/docs/guides/hiding-a-version.rst +++ b/docs/guides/hiding-a-version.rst @@ -17,4 +17,4 @@ Go to the :guilabel:`Versions` tab of your project, click on :guilabel:`Edit` an Users that have a link to your old version will still be able to see your docs. And new users can see all your versions (including hidden versions) in the versions tab of your project at ``https://readthedocs.org/projects//versions/`` -Check the docs about :ref:`versions' states ` for more information. +Check the docs about :ref:`versions' states ` for more information. diff --git a/docs/guides/index.rst b/docs/guides/index.rst index a0e5129817a..57b459f7fb4 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -1,3 +1,5 @@ +:orphan: + Guides ====== @@ -6,56 +8,9 @@ related to Read the Docs itself, documentation tools like Sphinx and MkDocs and how to write successful documentation. -Sphinx & MkDocs how-to guides ------------------------------ - -These guides will help you get the most out of your documentation authoring tool -whether that is Sphinx or MkDocs. - -.. toctree:: - :maxdepth: 1 - - adding-custom-css - custom-404-page - intersphinx - manage-translations - mkdocs-old-versions - pdf-non-ascii-languages - remove-edit-buttons - vcs - - -Read the Docs how-to guides ---------------------------- - -These guides will help you customize or tune aspects of Read the Docs. - -.. toctree:: - :maxdepth: 1 - - autobuild-docs-for-pull-requests - build-notifications - build-using-too-many-resources - canonical - conda - environment-variables - feature-flags - google-analytics - hiding-a-version - searching-with-readthedocs - sitemaps - specifying-dependencies - technical-docs-seo-guide - wipe-environment - - -Read the Docs for Business how-to guides ----------------------------------------- - -These guides are specific to :doc:`/commercial/index`. - .. toctree:: :maxdepth: 1 - private-python-packages - private-submodules + tools + platform + commercial diff --git a/docs/guides/platform.rst b/docs/guides/platform.rst new file mode 100644 index 00000000000..142829f42f8 --- /dev/null +++ b/docs/guides/platform.rst @@ -0,0 +1,21 @@ +Read the Docs Guides +-------------------- + +These guides will help you customize or tune aspects of Read the Docs. + +.. toctree:: + :maxdepth: 1 + + autobuild-docs-for-pull-requests + build-notifications + build-using-too-many-resources + canonical + conda + environment-variables + feature-flags + google-analytics + hiding-a-version + searching-with-readthedocs + specifying-dependencies + technical-docs-seo-guide + wipe-environment diff --git a/docs/guides/searching-with-readthedocs.rst b/docs/guides/searching-with-readthedocs.rst index a5f4a35e6cd..e7de8283114 100644 --- a/docs/guides/searching-with-readthedocs.rst +++ b/docs/guides/searching-with-readthedocs.rst @@ -1,48 +1,20 @@ Searching with Read the Docs ============================ -Read the Docs uses Elasticsearch to provide a better search experience. +Read the Docs uses :doc:`/server-side-search` to power our search. This guide explains how to add a "search as you type" feature to your documentation, -how to use advanced query syntax to get more accurate results, -and how to use other search features that Read the Docs supports. -Where appropriate, example searches are provided. - -You can find information on the search architecture and how we index document in our -:doc:`Search <../development/search>` docs. +and how to use advanced query syntax to get more accurate results. +You can find information on the search architecture and how we index documents in our +:doc:`Search ` docs. .. contents:: Table of contents :local: :backlinks: none :depth: 3 - -Improvements over Sphinx search -------------------------------- - -Sphinx is designed to create a self-contained webpage and all search indexing is performed at the time when the documentation is built. -This means that it is not possible for Sphinx to add features such as searching translations or subprojects or providing analytics on common searches. -Read the Docs supports a powerful documentation search, unlike Sphinx, which has support only for a basic search function. - -Features of Read the Docs documentation search are: - -- Search-as-you-type feature supported. -- Search analytics. -- Search across multiple projects. -- Search inside subprojects. -- Advanced query syntax. -- Improved search result order. -- Public search API (documentation pending). -- Case insensitive search. -- Results from sections of the documentation. -- Code search. - - -Search features for project admins ----------------------------------- - Enable "search as you type" in your documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------- `readthedocs-sphinx-search`_ is a Sphinx extension that integrates your documentation more closely with the search implementation of Read the Docs. @@ -54,59 +26,15 @@ you can press :guilabel:`/` (forward slash) and start typing or just visit these - https://docs.readthedocs.io/?rtd_search=contributing - https://docs.readthedocs.io/?rtd_search=api/v3/projects/ - -Search analytics -~~~~~~~~~~~~~~~~ - -Search queries are recorded and stored in a database in order to provide analytics to the project admins. -These analytics make it easy to know what your users are looking for in your documentation. -You can see these analytics in your project admin dashboard. - -.. figure:: /_static/images/guides/search-analytics-demo.png - :width: 40% - :align: center - :alt: Search analytics in project admin dashboard - - Search analytics demo - - -Search features for readers ---------------------------- - -Search across all projects -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Our `main site search`_ supports searching for projects and searching across all projects. -You can also use it to select the specific project and version to narrow down the search results. - -Example queries: - -- https://readthedocs.org/search/?q=celery&type=project -- https://readthedocs.org/search/?q=celery._state&type=file -- https://readthedocs.org/search/?q=celery._state&type=file&project=celery -- https://readthedocs.org/search/?q=celery._state&type=file&project=celery&version=master - - -Search inside subprojects -~~~~~~~~~~~~~~~~~~~~~~~~~ - -We allow projects to be configured as subprojects of another project. -You can read more about this in our :doc:`Subprojects <../subprojects>` documentation. - -If a search is made in a project which has one or more subprojects under it, -the search results include the results from those subprojects: projects share search indexes with their parent- and sibling-projects. -For example: If `Kombu`_ is a subproject of `Celery`_ and you search in Celery docs, then the results from Kombu will also be there. -Example: https://docs.celeryproject.org/en/master/search.html?q=utilities&check_keywords=yes&area=default - - Search query syntax -~~~~~~~~~~~~~~~~~~~ +------------------- -Read the Docs uses the `Simple Query String`_ feature of `Elasticsearch`_. -This means that as the search query becomes more complex, the results yielded become more specific. +Read the Docs uses the `Simple Query String`_ feature from `Elasticsearch`_. +This means that as the search query becomes more complex, +the results yielded become more specific. Exact phrase search -+++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~ If a query is wrapped in ``"`` (double quotes), then only those results where the phrase is exactly matched will be returned. @@ -118,7 +46,7 @@ Example queries: - https://docs.readthedocs.io/?rtd_search=%22when%20a%20404%20is%20returned%22 Exact phrase search with slop value -+++++++++++++++++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``~N`` (tilde N) after a phrase signifies slop amount. It can be used to match words that are near one another. @@ -130,7 +58,7 @@ Example queries: - https://docs.readthedocs.io/?rtd_search=%22read%20the%20docs%20story%22~5 Prefix query -++++++++++++ +~~~~~~~~~~~~ ``*`` (asterisk) at the end of any term signifies a prefix query. It returns the results containing the words with specific prefix. @@ -142,7 +70,7 @@ Example queries: - https://docs.readthedocs.io/?rtd_search=build*%20and%20c*%20to%20doc* Fuzzy query -+++++++++++ +~~~~~~~~~~~ ``~N`` after a word signifies edit distance (fuzziness). This type of query is helpful when the exact spelling of the keyword is unknown. @@ -155,23 +83,18 @@ Example queries: - https://docs.readthedocs.io/?rtd_search=configurtion~1 -Using the search query syntax to build complex queries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Build complex queries +~~~~~~~~~~~~~~~~~~~~~ -The search query syntaxes described in the previous section can be used with one another to build complex queries. +The search query syntaxes described in the previous sections can be used with one another to build complex queries. -Example queries: +For example: - https://docs.readthedocs.io/?rtd_search=auto*%20redirect* - https://docs.readthedocs.io/?rtd_search=abandon*%20proj* - https://docs.readthedocs.io/?rtd_search=localisation~3%20of%20doc* - +.. _Elasticsearch: https://www.elastic.co/products/elasticsearch .. _readthedocs-sphinx-search: https://readthedocs-sphinx-search.readthedocs.io/ -.. _GitHub issues: https://github.com/readthedocs/readthedocs.org/issues/new -.. _main site search: https://readthedocs.org/search/?q=&type=file&version=latest -.. _Kombu: http://docs.celeryproject.org/projects/kombu/en/master/ -.. _Celery: http://docs.celeryproject.org/en/master/ .. _Simple Query String: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html# -.. _Elasticsearch: https://www.elastic.co/products/elasticsearch .. _Levenshtein edit distance: https://en.wikipedia.org/wiki/Levenshtein_distance diff --git a/docs/guides/sitemaps.rst b/docs/guides/sitemaps.rst deleted file mode 100644 index 871fdcb5b6c..00000000000 --- a/docs/guides/sitemaps.rst +++ /dev/null @@ -1,19 +0,0 @@ -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: - -* when it was last updated, -* how often it changes, -* how important it is in relation to other URLs in the site, and -* what translations are available for a page. - -Read the Docs automatically generates a sitemap for each project that hosts -to improve results when performing a search on these search engines. -This allow us to prioritize results based on the version number, for example -to show ``stable`` as the top result followed by ``latest`` and then all the project's -versions sorted following semver_. - -.. _semver: https://semver.org/ -.. _Sitemaps: https://www.sitemaps.org/ diff --git a/docs/guides/technical-docs-seo-guide.rst b/docs/guides/technical-docs-seo-guide.rst index 30be1b7f168..f7b66e7d6f5 100644 --- a/docs/guides/technical-docs-seo-guide.rst +++ b/docs/guides/technical-docs-seo-guide.rst @@ -197,7 +197,7 @@ or any alternate language versions of a page. Read the Docs generates a sitemap for you that contains the last time your documentation was updated as well as links to active versions, subprojects, and translations your project has. -We have a small separate guide on :doc:`sitemaps `. +We have a small separate guide on :ref:`sitemaps `. See the `Google docs on building a sitemap `_. diff --git a/docs/guides/tools.rst b/docs/guides/tools.rst new file mode 100644 index 00000000000..3859e7cf9a9 --- /dev/null +++ b/docs/guides/tools.rst @@ -0,0 +1,16 @@ +Sphinx & MkDocs Guides +---------------------- + +These guides will help you get the most out of your documentation authoring tool +whether that is Sphinx or MkDocs. + +.. toctree:: + :maxdepth: 1 + + adding-custom-css + intersphinx + manage-translations + mkdocs-old-versions + pdf-non-ascii-languages + remove-edit-buttons + vcs \ No newline at end of file diff --git a/docs/hosting.rst b/docs/hosting.rst new file mode 100644 index 00000000000..375c8a82f4d --- /dev/null +++ b/docs/hosting.rst @@ -0,0 +1,107 @@ +Documentation Hosting Features +============================== + +The main way that users interact with your documentation is via the hosted HTML that we serve. +We support a number of important features that you would expect for a documentation host. + +.. contents:: Contents + :local: + :depth: 1 + +Content Delivery Network (CDN) +------------------------------ + +A CDN is used for making documentation pages faster for your users. +This is done by caching the documentation page content in multiple data centers around the world, +and then serving docs from the data center closest to the user. + +We support CDN's on both of our sites, +as we talk about below. + +.. tabs:: + + .. tab:: |org_brand| + + On |org_brand|, + we are able to provide a CDN to all the projects that we host. + This service is graciously sponsored by `CloudFlare`_. + + We bust the cache on the CDN when the following actions happen: + + * Your Project is saved + * Your Domain is saved + * A new version is built + + + .. tab:: |com_brand| + + On |com_brand|, + we offer a CDN as part of our Enterprise plan. + Please contact support@readthedocs.com to discuss how we can enable this for you. + +.. _CloudFlare: https://www.cloudflare.com/ + +Sitemaps +-------- + +`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: + +* when it was last updated, +* how often it changes, +* how important it is in relation to other URLs in the site, and +* what translations are available for a page. + +Read the Docs automatically generates a sitemap for each project that hosts +to improve results when performing a search on these search engines. +This allow us to prioritize results based on the version number, for example +to show ``stable`` as the top result followed by ``latest`` and then all the project's +versions sorted following `semantic versioning`_. + +.. _semantic versioning: https://semver.org/ + +Custom Not Found (404) Pages +---------------------------- + +If you want your project to use a custom page for not found pages instead of the "Maze Found" default, +you can put a ``404.html`` at the top level of your project's HTML output. + +When a 404 is returned, Read the Docs checks if there is a ``404.html`` in the root of your project's output and uses it if it exists. + +We recommend the `sphinx-notfound-page`_ extension, +which Read the Docs maintains. +It automatically creates a ``404.html`` page for your documentation, +matching the theme of your project. +See its documentation_ for how to install and customize it. + +.. _sphinx-notfound-page: https://pypi.org/project/sphinx-notfound-page +.. _documentation: https://sphinx-notfound-page.readthedocs.io/ + +Custom robots.txt Pages +----------------------- + +`robots.txt`_ files allow you to customize how your documentation is indexed in search engines. +We automatically generate one for you, +which automatically hides versions which are set to :ref:`versions:Hidden`. + +The ``robots.txt`` file will be served from the **default version** of your Project. +This is because the ``robots.txt`` file is served at the top-level of your domain, +so we must choose a version to find the file in. +The **default version** is the best place to look for it. + +Sphinx and Mkdocs both have different ways of outputting static files in the build: + +Sphinx +~~~~~~ + +Sphinx uses `html_extra_path`_ option to add static files to the output. +You need to create a ``robots.txt`` file and put it under the path defined in ``html_extra_path``. + +MkDocs +~~~~~~ + +MkDocs needs the ``robots.txt`` to be at the directory defined at `docs_dir`_ config. + +.. _robots.txt: https://developers.google.com/search/reference/robots_txt +.. _html_extra_path: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path +.. _docs_dir: https://www.mkdocs.org/user-guide/configuration/#docs_dir diff --git a/docs/index.rst b/docs/index.rst index 0ccea91c2dc..7b0bd26f8f8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,29 +4,34 @@ Read the Docs: Documentation Simplified .. meta:: :description lang=en: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs. - `Read the Docs`_ simplifies software documentation -by automating building, versioning, and hosting of your docs for you. +by building, versioning, and hosting of your docs, automatically. Think of it as *Continuous Documentation*. -Never out of sync +Never out of sync |:arrows_counterclockwise:| Whenever you push code to your favorite version control system, whether that is Git, Mercurial, Bazaar, or Subversion, Read the Docs will automatically build your docs so your code and documentation are always up-to-date. + Read more about :doc:`/webhooks`. -Multiple versions +Multiple versions |:card_index_dividers:| Read the Docs can host and build multiple versions of your docs so having a 1.0 version of your docs and a 2.0 version of your docs is as easy as having a separate branch or tag in your version control system. + Read more about :doc:`/versions`. -Free and open source - Read the Docs is free and open source and hosts documentation - for nearly 100,000 large and small open source projects +Open Source and User Focused |:heartbeat:| + Our code is free and `open source `_. + :doc:`Our company ` is bootstrapped and 100% user focused. + |org_brand| hosts documentation for over 100,000 large + and small open source projects, in almost every human and computer language. + |com_brand| supports hundreds of organizations with product and internal documentation. .. _Read the docs: https://readthedocs.org/ +You can find out more about our all the :doc:`/features` in these pages. First steps ----------- @@ -37,11 +42,12 @@ Learn about documentation authoring tools such as Sphinx and MkDocs to help you create fantastic documentation for your project. * **Getting started**: - :doc:`With Sphinx ` | - :doc:`With MkDocs ` + :doc:`With Sphinx ` | + :doc:`With MkDocs ` | + :doc:`Feature Overview ` * **Importing your existing documentation**: - :doc:`Import guide ` + :doc:`Import guide ` .. toctree:: @@ -53,6 +59,7 @@ to help you create fantastic documentation for your project. intro/getting-started-with-mkdocs intro/import-guide + features Getting started with Read the Docs @@ -62,45 +69,67 @@ 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 ` + :doc:`Incoming webhooks ` | + :doc:`/custom_domains` | + :doc:`/versions` | + :doc:`/downloadable-documentation` | + :doc:`/hosting` | + :doc:`/server-side-search` * **Connecting with GitHub, BitBucket, or GitLab**: - :doc:`Connecting your account ` + :doc:`Connecting your VCS account ` | + :doc:`VCS webhooks ` -* **Read the Docs build and versioning process**: - :doc:`Build process ` | - :doc:`Handling multiple docs versions ` +* **Read the Docs build process**: + :doc:`Configuration reference ` | + :doc:`Build process ` | + :doc:`/badges` | * **Troubleshooting**: - :doc:`support` | - :doc:`Frequently asked questions ` + :doc:`/support` | + :doc:`Frequently asked questions ` .. toctree:: :maxdepth: 1 :hidden: :caption: Getting started - features + /config-file/index + /webhooks + /custom_domains + /versions + /downloadable-documentation + /server-side-search + /hosting + + /connected-accounts - config-file/index - webhooks - badges - custom_domains + /builds + /badges - connected-accounts + /support + /faq - builds - versions - support - faq +Step-by-step Guides +------------------- +These guides will help walk you through specific use cases +related to Read the Docs itself, documentation tools like Sphinx and MkDocs +and how to write successful documentation. + +* :doc:`/guides/tools` +* :doc:`/guides/platform` +* :doc:`/guides/commercial` + +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Step-by-step Guides + + /guides/tools + /guides/platform + /guides/commercial Advanced features of Read the Docs ---------------------------------- @@ -112,11 +141,12 @@ 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 ` +.. TODO: Move user-defined to Getting started, they are core functionality + * **Redirects**: :doc:`User defined redirects ` | :doc:`Automatic redirects ` @@ -147,7 +177,6 @@ out of your documentation and Read the Docs. automation-rules - guides/index api/index @@ -174,6 +203,7 @@ of Read the Docs and the larger software documentation ecosystem. :doc:`Release notes & changelog ` * **The people and philosophy behind Read the Docs**: + :doc:`About Us ` | :doc:`Team ` | :doc:`Open source philosophy ` | :doc:`Our story ` @@ -207,6 +237,7 @@ of Read the Docs and the larger software documentation ecosystem. abandoned-projects changelog + about team open-source-philosophy story diff --git a/docs/intro/getting-started-with-mkdocs.rst b/docs/intro/getting-started-with-mkdocs.rst index 11739710d0c..b135e6dca8f 100644 --- a/docs/intro/getting-started-with-mkdocs.rst +++ b/docs/intro/getting-started-with-mkdocs.rst @@ -51,8 +51,7 @@ Open up http://127.0.0.1:8000/ in your web browser to see your documentation. You can make changes to your Markdown files and your docs will automatically rebuild. .. figure:: ../_static/images/first-steps/mkdocs-hello-world.png - :align: right - :figwidth: 300px + :figwidth: 500px :target: ../_static/images/first-steps/mkdocs-hello-world.png Your MkDocs project is built @@ -62,6 +61,11 @@ you can start using Read the Docs by :doc:`importing your docs ` + used for your project to build the docs to avoid potential future incompatibilities. + External resources ------------------ diff --git a/docs/intro/getting-started-with-sphinx.rst b/docs/intro/getting-started-with-sphinx.rst index 2fb1dca362b..192aaeaeaad 100644 --- a/docs/intro/getting-started-with-sphinx.rst +++ b/docs/intro/getting-started-with-sphinx.rst @@ -72,8 +72,7 @@ in your documentation output directory (typically ``_build/html/index.html``). Open this file in your web browser to see your docs. .. figure:: ../_static/images/first-steps/sphinx-hello-world.png - :align: right - :figwidth: 300px + :figwidth: 500px :target: ../_static/images/first-steps/sphinx-hello-world.png Your Sphinx project is built diff --git a/docs/server-side-search.rst b/docs/server-side-search.rst new file mode 100644 index 00000000000..08155d00cdb --- /dev/null +++ b/docs/server-side-search.rst @@ -0,0 +1,61 @@ +Server Side Search +================== + +Read the Docs provides full-text search across all of the pages of all projects, +this is powered by Elasticsearch_. +You can search all projects at https://readthedocs.org/search/, +or search only on your project from the :guilabel:`Search` tab of your project. + +We override the default search engine of your project with our search engine +to provide you better results within your project. +We fallback to the built-in search engine from your project +if our search engine doesn't return any results, +just in case we missed something |:smile:| + +Search features +--------------- + +We offer a number of benefits compared to other documentation hosts: + +Search across :doc:`subprojects ` + Subprojects allow you to host multiple discrete projects on a single domain. + Every project hosted on that same domain is included in results for search. + +Search results land on the exact content you were looking for + We index every heading in the document, + allowing you to get search results exactly to the content that you are searching for. + Try this out by searching for `"full-text search"`_. + +Search across projects you have access to (|com_brand|) + This allows you to search across all the projects you access to in your Dashboard. + **Don't remember where you found that document the other day? + No problem, you can search across them all.** + +Special query syntax for more specific results. + We support a full range of search queries. + You can see some examples in our :ref:`guides/searching-with-readthedocs:search query syntax` guide. + +.. + Code object searching + With the user of :doc:`Sphinx Domains ` we are able to automatically provide direct search results to your Code objects. + You can try this out with our docs here by searching for + TODO: Find good examples in our docs, API maybe? + +.. _"full-text search": https://docs.readthedocs.io/en/latest/search.html?q=%22full-text+search%22 + +Analytics +--------- + +Know what your users are looking for in your docs. +To see a list of the top queries and an overview from the last month, +go to the :guilabel:`Admin` tab of your project, +and then click on :guilabel:`Search Analytics`. + +.. figure:: /_static/images/search-analytics-demo.png + :width: 50% + :align: center + :alt: Search analytics demo + + Search analytics demo + +.. _Elasticsearch: https://www.elastic.co/products/elasticsearch diff --git a/docs/support.rst b/docs/support.rst index 3e4a5b4386a..d60d599feca 100644 --- a/docs/support.rst +++ b/docs/support.rst @@ -14,25 +14,21 @@ Good questions for Stack Overflow would be: * "How do I structure translations inside of my project for easiest contribution from users?" * "How do I use Sphinx to use SVG images in HTML output but PNG in PDF output?" -Community Support ------------------ +User Support +------------ -Read the Docs is supported by community contributions and advertising. -We hope to bring in enough money -with our `Gold`_ and `Ethical Ads`_ programs to keep Read the Docs sustainable. - -**All people answering your questions are doing it with their own time, -so please be kind and provide as much information as possible.** +If you need a specific request for your project or account, +like more resources, change of the project's slug or username. +Send an email to support@readthedocs.org. +We will get to you as soon as possible. -Bugs & Support Issues -~~~~~~~~~~~~~~~~~~~~~ +Bug Reports +----------- You can file bug reports on our `GitHub issue tracker`_, and they will be addressed as soon as possible. -**Support is a volunteer effort**, -and there is no guaranteed response time. -If you need answers quickly, -you can buy commercial support below. +Please only file issues with our actual codebase there, +not user support questions Reporting Issues ~~~~~~~~~~~~~~~~ @@ -47,23 +43,12 @@ This includes: * Expected result * Actual result -Specific Requests -~~~~~~~~~~~~~~~~~ - -If you need a specific request for your project or account, -like more resources, change of the project's slug or username. -Send an email to support@readthedocs.org. +Priority Support +---------------- -Commercial Support ------------------- - -We offer commercial support with :doc:`Read the Docs for Business ` +We offer priority support with :doc:`Read the Docs for Business ` and we have a dedicated team that responds to support requests during business hours. -For consulting services around documentation systems, -you can `contact us `_ -or read more at https://readthedocs.com/services/#open-source-support. - .. _Stack Overflow: https://stackoverflow.com/questions/tagged/read-the-docs .. _Github Issue Tracker: https://github.com/readthedocs/readthedocs.org/issues .. _Gold: https://readthedocs.org/accounts/gold/ diff --git a/docs/user-defined-redirects.rst b/docs/user-defined-redirects.rst index e43348cd7d8..5dfc1165745 100644 --- a/docs/user-defined-redirects.rst +++ b/docs/user-defined-redirects.rst @@ -8,8 +8,8 @@ Quick Summary * Log into your readthedocs.org account. * From your dashboard, select the project on which you wish to add redirects. -* From the project's top navigation bar, select the Admin tab. -* From the left navigation menu, select Redirects. +* From the project's top navigation bar, select the :guilabel:`Admin` tab. +* From the left navigation menu, select :guilabel:`Redirects`. * In the form box "Redirect Type" select the type of redirect you want. See below for detail. * Depending on the redirect type you select, enter FROM and/or TO URL as needed. * When finished, click the SUBMIT Button. diff --git a/docs/versions.rst b/docs/versions.rst index afe0fbf490e..e5a18ae989e 100644 --- a/docs/versions.rst +++ b/docs/versions.rst @@ -1,8 +1,8 @@ -Versions -======== +Versioned Documentation +======================= Read the Docs supports multiple versions of your repository. -On the initial import, +On initial import, we will create a ``latest`` version. This will point at the default branch for your VCS control: ``master``, ``default``, or ``trunk``. @@ -12,6 +12,9 @@ if your project has any tagged releases. If you want a custom ``stable`` version, create either a tag or branch in your project with that name. +When you have :doc:`/webhooks` configured for your repository, +we will automatically build each version when you push a commit. + How we envision versions working -------------------------------- @@ -42,24 +45,8 @@ which are branches that are maintained over time for a specific release number. .. _PEP 440: https://www.python.org/dev/peps/pep-0440/ -Tags and branches ------------------ - -Read the Docs supports two workflows for versioning: based on tags or branches. -If you have at least one tag, -tags will take preference over branches when selecting the stable version. - -Redirects on root URLs ----------------------- - -When a user hits the root URL for your documentation, -for example ``http://pip.readthedocs.io/``, -they will be redirected to the **Default version**. -This defaults to **latest**, -but could also point to your latest released version. - -States ------- +Version States +-------------- States define the visibility of a version across the site. You can change the states of a version from the :guilabel:`Versions` tab of your project. @@ -105,6 +92,27 @@ This is useful when: Active versions that are hidden will be listed as ``Disallow: /path/to/version/`` in the default `robots.txt file `__ created by Read the Docs. +Tags and branches +----------------- + +Read the Docs supports two workflows for versioning: based on tags or branches. +If you have at least one tag, +tags will take preference over branches when selecting the stable version. + +Version Control Support Matrix +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++------------+------------+-----------+------------+-----------+ +| | git | hg | bzr | svn | ++============+============+===========+============+===========+ +| Tags | Yes | Yes | Yes | No | ++------------+------------+-----------+------------+-----------+ +| Branches | Yes | Yes | Yes | No | ++------------+------------+-----------+------------+-----------+ +| Default | master | default | | trunk | ++------------+------------+-----------+------------+-----------+ + + Version warning --------------- @@ -113,3 +121,13 @@ This banner has a text with a link redirecting the users to the latest version o This feature is disabled by default on new projects, you can enable it in the admin section of your docs (:guilabel:`Admin` > :guilabel:`Advanced Settings`). + + +Redirects on root URLs +---------------------- + +When a user hits the root URL for your documentation, +for example ``http://pip.readthedocs.io/``, +they will be redirected to the **Default version**. +This defaults to **latest**, +but could also point to your latest released version. \ No newline at end of file diff --git a/docs/webhooks.rst b/docs/webhooks.rst index ab01781c0c6..232a81aa308 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -1,10 +1,10 @@ -Webhooks -======== +Incoming Webhooks and Automation +================================ The primary method that Read the Docs uses to detect changes to your documentation and versions is through the use of *webhooks*. Webhooks are configured with -your repository provider, such as GitHub, Bitbucket or GitLab, and with each commit, -merge, or other change to your repository, Read the Docs is notified. When we +your repository provider, such as GitHub, Bitbucket or GitLab, +and with each change to your repository, Read the Docs is notified. When we receive a webhook notification, we determine if the change is related to an active version for your project, and if it is, a build is triggered for that version. @@ -12,8 +12,8 @@ version. Webhook Integrations -------------------- -You'll find a list of configured webhook integrations on your project's admin -dashboard, under **Integrations**. You can select any of these integrations to +You'll find a list of configured webhook integrations on your project's :guilabel:`Admin` +dashboard, under :guilabel:`Integrations`. You can select any of these integrations to see the *integration detail page*. This page has additional configuration details and a list of HTTP exchanges that have taken place for the integration. @@ -26,7 +26,7 @@ Webhook Creation ---------------- If you have :doc:`connected your Read the Docs account ` to GitHub, Bitbucket, or GitLab, -a webhook will be set up automatically for your repository. However, if your +**a webhook will be set up automatically for your repository**. However, if your project was not imported through a connected account, you may need to manually configure a webhook for your project. diff --git a/requirements/local-docs-build.txt b/requirements/local-docs-build.txt index 2b91a4b4d49..d69ab1c1d06 100644 --- a/requirements/local-docs-build.txt +++ b/requirements/local-docs-build.txt @@ -29,6 +29,7 @@ mkdocs==1.1 Markdown==3.2.1 # Docs +sphinxemoji==0.1.5 sphinxcontrib-httpdomain==1.7.0 sphinx-prompt==1.0.0 sphinx-notfound-page==0.4