diff --git a/docs/user/faq.rst b/docs/user/faq.rst index 5436e1c6132..8ef267a92bd 100644 --- a/docs/user/faq.rst +++ b/docs/user/faq.rst @@ -1,65 +1,71 @@ Frequently Asked Questions ========================== -My project isn't building correctly ------------------------------------ +.. contents:: + :local: -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`. +.. + Frequently asked questions should be questions that actually got asked. + Formulate them as a question and an answer. + Consider that the answer is best as a reference to another place in the documentation. -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`. +Building and publishing your project +------------------------------------ -Help, my build passed but my documentation page is 404 Not Found! ------------------------------------------------------------------ -This often happens because you don't have an `index.html` file being generated. -Make sure you have one of the following files: +.. Old reference +.. _My project isn't building correctly: - * `index.rst` - * `index.md` +Why does my project have status "failing"? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -At the top level of your built documentation, -otherwise we aren't able to serve a "default" index page. +Projects have the status "failing" because something in the build process has failed. +This can be because the project is not correctly configured, +because the contents of the Git repository cannot be built, +or in the most rare cases because a system that Read the Docs connects to is not working. -To test if your docs actually built correctly, -you can navigate to a specific page (`/en/latest/README.html` for example). +First, you should check out the Builds tab of your project. +By clicking on the failing step, +you will be able to see details that can lead to resolutions to your build error. +If the solution is not self-evident, +you can use an important word or message from the error to search for a solution. -My documentation requires additional dependencies -------------------------------------------------- +.. seealso:: -For most Python dependencies, you can can specify a requirements file -which details your dependencies. See our guide on :ref:`guides/reproducible-builds:using a configuration file`. -You can also set your project documentation to install your project itself -as a dependency. + :doc:`/build-troubleshooting` + Common errors and solutions for build failures. -Your build may depend on extensions that require additional system packages to -be installed. If you are using a :doc:`Configuration File ` you -can :ref:`add libraries with apt ` to the -Ubuntu-based builder . + Other FAQ entries + * :ref:`faq:My documentation requires additional dependencies` + * :ref:`faq:I get import errors on libraries that depend on C modules` -If your project or its dependencies rely on C libraries that cannot be installed -this way, see :ref:`faq:I get import errors on libraries that depend on C modules`. +.. Old reference +.. _Help, my build passed but my documentation page is 404 Not Found!: -My project requires some additional settings --------------------------------------------- +My build says "passed" but I get a 404 page - why? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If this is just a dependency issue, -see :ref:`faq:My documentation requires additional dependencies`. +This often happens because you don't have an `index.html` file being generated. -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 `. +Make sure you have one of the following files at the top level of your documentation source: + + * `index.rst` (Sphinx) + * `index.md` (MkDocs or Sphinx with MyST) + +.. tip:: + To test if your docs actually built correctly, + you can navigate to a specific page that you know is part of the documentation build, + for example `/en/latest/README.html`. -I get import errors on libraries that depend on C modules ---------------------------------------------------------- +.. Old reference +.. _I get import errors on libraries that depend on C modules: + +Why do I get import errors from libraries depending on C modules? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: @@ -77,32 +83,164 @@ the C-dependent libraries from your ``install_requires`` in the RTD environment. .. _autodoc_mock_imports: http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports +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. + +You can specify an exact path to your documentation using a Read the Docs :doc:`config-file/index`. + +How can I avoid search results having a deprecated version of my docs? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If readers search something related to your docs in Google, it will probably return the most relevant version of your documentation. +It may happen that this version is already deprecated and you want to stop Google indexing it as a result, +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. + + +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. + + +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 + +We also keep an up-to-date :doc:`changelog `. + + + +Additional features and configuration +------------------------------------- + +.. Old reference +.. _My documentation requires additional dependencies: + +How do I add additional software dependencies for my documentation? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For most Python dependencies, +you can can specify a requirements file which details your dependencies. +You can also set your project documentation to install your Python project itself as a dependency. + +.. seealso:: + + :doc:`/builds` + An overview of the build process. + + :doc:`/guides/reproducible-builds` + General information about adding dependencies and best-practices for maintaining them. + + :doc:`/build-customization` + How to customize your builds, for example if you need to build with different tools from Sphinx or + if you need to add additional packages for the Ubuntu-based builder. + + :doc:`Configuration File ` + Reference for the main configuration file, `.readthedocs.yaml` + + :ref:`build.apt_packages ` + Reference for adding Debian packages with apt for the Ubuntu-based builders + + Other FAQ entries + * :ref:`faq:My documentation requires additional dependencies` + * :ref:`faq:I get import errors on libraries that depend on C modules` + + +.. Old reference +.. _My project requires some additional settings: + +Can I have access to additional features or settings? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If this is just a dependency issue, +see :ref:`faq:My documentation requires additional dependencies`. + +Read the Docs offers some settings (feature flags) 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. + +.. seealso:: + + :doc:`/feature-flags` + Reference of all Feature Flags that can be requested. + 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:: +can vary the behavior based on this. For example: + +.. code-block:: python import os - on_rtd = os.environ.get('READTHEDOCS') == 'True' + + on_rtd = os.environ.get("READTHEDOCS") == "True" if on_rtd: - html_theme = 'default' + html_theme = "default" else: - html_theme = 'nature' + 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:: +environment, and will be set to ``True`` when building on RTD: + + +.. code-block:: jinja {% if READTHEDOCS %} Woo {% endif %} +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. + +.. _Disqus: https://disqus.com/ +.. _sphinxcontrib-disqus: https://pypi.python.org/pypi/sphinxcontrib-disqus + +Can I remove advertising from my documentation? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. See :ref:`Opting out of advertising `. + + +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. + +Big projects +------------ How do I host multiple projects on one custom domain? ------------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We support the concept of subprojects, which allows multiple projects to share a single domain. If you add a subproject to a project, that documentation will @@ -122,19 +260,19 @@ You can add subprojects in the project admin dashboard. For details on custom domains, see our documentation on :doc:`/custom-domains`. +How do I support multiple languages of documentation? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Where do I need to put my docs for RTD to find it? --------------------------------------------------- +Read the Docs supports multiple languages. +See the section on :doc:`localization`. -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`. +Sphinx +------ I want to use the Blue/Default Sphinx theme -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ We think that our theme is badass, and better than the default for many reasons. @@ -146,36 +284,58 @@ The value of this doesn't matter, and can be set to ``/default.css`` for default I want to use the Read the Docs theme locally ---------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Read the Docs automatically applies the sphinx-rtd-theme to projects that do not have a defined theme. +If you build a Sphinx project locally, +you should specify that you are using sphinx-rtd-theme. + +.. seealso:: -There is a repository for that: https://github.com/readthedocs/sphinx_rtd_theme. -Simply follow the instructions in the README. + `sphinx-rtd-theme documentation `_ + See the official documentation for instructions to enable it in your Sphinx theme. 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 --------------------------- +Python +------ -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. +Can I document a Python package that is not at the root of my repository? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _Disqus: https://disqus.com/ -.. _sphinxcontrib-disqus: https://pypi.python.org/pypi/sphinxcontrib-disqus +Yes. The most convenient way to access a Python package for example via +`Sphinx's autoapi`_ in your documentation is to use the *Install your project +inside a virtualenv using setup.py install* option in the admin panel of +your project. However this assumes that your ``setup.py`` is in the root of +your repository. +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.txt`` file with the +following contents:: -How do I support multiple languages of documentation? ------------------------------------------------------ + src/python/ -See the section on :doc:`localization`. +Please note that the path must be relative to the working directory where ``pip`` is launched, +rather than the directory where the requirements file is located. +Therefore, even if you want to move the requirements file to a ``requirements/`` directory, +the example path above would work. +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 Does Read the Docs work well with "legible" docstrings? -------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Yes. One criticism of Sphinx is that its annotated docstrings are too dense and difficult for humans to read. In response, many projects @@ -199,38 +359,9 @@ 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 :ref:`guide `. -Can I document a Python package that is not at the root of my repository? -------------------------------------------------------------------------- - -Yes. The most convenient way to access a Python package for example via -`Sphinx's autoapi`_ in your documentation is to use the *Install your project -inside a virtualenv using setup.py install* option in the admin panel of -your project. However this assumes that your ``setup.py`` is in the root of -your repository. - -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.txt`` file with the -following contents:: - - src/python/ - -Please note that the path must be relative to the working directory where ``pip`` is launched, -rather than the directory where the requirements file is located. -Therefore, even if you want to move the requirements file to a ``requirements/`` directory, -the example path above would work. - -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 - I need to install a package in a environment with pinned versions ------------------------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To ensure proper installation of a Python package, the ``pip`` :ref:`install method ` will automatically upgrade every dependency to its most recent version in case they aren't pinned by the package definition. If instead you'd like to pin your dependencies outside the package, you can add this line to your requirements or environment file (if you are using Conda). @@ -247,7 +378,7 @@ In your Conda environment file (``environment.yml``):: Can I use Anaconda Project and ``anaconda-project.yml``? --------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Yes. With ``anaconda-project>=0.8.4`` you can use the `Anaconda Project`_ configuration file ``anaconda-project.yaml`` (or ``anaconda-project.yml``) directly in place of a @@ -264,60 +395,13 @@ in the ``.readthedocs.yaml`` config file if it contains:: .. _Anaconda Project: https://anaconda-project.readthedocs.io/en/latest/ -How can I avoid search results having a deprecated version of my docs? ----------------------------------------------------------------------- - -If readers search something related to your docs in Google, it will probably return the most relevant version of your documentation. -It may happen that this version is already deprecated and you want to stop Google indexing it as a result, -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. - - -Can I remove advertising from my documentation? ------------------------------------------------ - -See :ref:`Opting out of advertising `. - - -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. - -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 - -We also keep an up-to-date :doc:`changelog `. +Other documentation frameworks +------------------------------ How can I deploy Jupyter Book projects on Read the Docs? --------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ According to `its own documentation `_, diff --git a/docs/user/index.rst b/docs/user/index.rst index 2e72c8b884c..1ae9fe57314 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -92,12 +92,12 @@ to help you create fantastic documentation for your project. :maxdepth: 2 :hidden: :caption: How-to Guides - :glob: /guides/authors /guides/administrators /guides/developers /examples + /faq .. toctree:: @@ -141,7 +141,7 @@ and some of the core features of Read the Docs. * **Troubleshooting**: :doc:`/support` | - :doc:`Frequently asked questions ` + :doc:`/faq` .. toctree:: :maxdepth: 1 @@ -163,7 +163,6 @@ and some of the core features of Read the Docs. /badges /support - /faq How-to Guides