From a3871e334fcd35e1d0db1ecef03bb3708496fc8b Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:05:59 -0500 Subject: [PATCH 01/19] Update "What's available" section --- docs/install.rst | 29 +++++++---------------------- 1 file changed, 7 insertions(+), 22 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 242b884d51e..c9f2f304bbc 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -149,29 +149,14 @@ with the name of any added project:: What's available ---------------- -After registering with the site (or creating yourself a superuser account), -you will be able to log in and view the `dashboard `_. - -From the dashboard you can import your existing -docs provided that they are in a git or mercurial repo. - - -Creating new Docs -^^^^^^^^^^^^^^^^^ - -One of the goals of `readthedocs.org `_ is to make it -easy for any open source developer to get high quality hosted docs with great -visibility! We provide a simple editor and two sample pages whenever -a new project is created. From there its up to you to fill in the gaps - we'll -build the docs, give you access to history on every revision of your files, -and we plan on adding more features in the weeks and months to come. - +After registering with the site (or creating yourself a superuser account), you +will be able to log in and view the `dashboard `_. Importing existing docs ^^^^^^^^^^^^^^^^^^^^^^^ -The other side of `readthedocs.org `_ is hosting the -docs you've already built. Simply provide us with the clone URL to your repo, -we'll pull your code, extract your docs, and build them! We make available -a post-commit webhook that can be configured to update the docs on our site -whenever you commit to your repo, effectively letting you 'set it and forget it'. +One of the goals of readthedocs.org is to make it easy for any open source +developer to get high quality hosted docs with great visibility! Simply provide +us with the clone URL to your repo, we'll pull your code, extract your docs, +and build them! We make available a post-commit webhook that can be configured +to update the docs whenever you commit to your repo. From dd24d42f581293e7cdc66b271d050820b7588046 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:18:35 -0500 Subject: [PATCH 02/19] Change title --- docs/install.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index c9f2f304bbc..201d9762aef 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -152,8 +152,8 @@ What's available After registering with the site (or creating yourself a superuser account), you will be able to log in and view the `dashboard `_. -Importing existing docs -^^^^^^^^^^^^^^^^^^^^^^^ +Importing your docs +^^^^^^^^^^^^^^^^^^^ One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility! Simply provide From 7cf9f9c1181e83909dd920156293f7e14e58a937 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:19:03 -0500 Subject: [PATCH 03/19] Add link to getting started page --- docs/install.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/install.rst b/docs/install.rst index 201d9762aef..cf7c3321dc7 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -159,4 +159,5 @@ One of the goals of readthedocs.org is to make it easy for any open source developer to get high quality hosted docs with great visibility! Simply provide us with the clone URL to your repo, we'll pull your code, extract your docs, and build them! We make available a post-commit webhook that can be configured -to update the docs whenever you commit to your repo. +to update the docs whenever you commit to your repo. See our +:doc:`getting_started` page to learn more. From 6e59fd0065fe5def2dda5288637523a1658de145 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:21:47 -0500 Subject: [PATCH 04/19] Wrap to 80 characters --- docs/install.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index cf7c3321dc7..6fbfbf7d015 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,10 +1,10 @@ .. _installing-read-the-docs: Installation -============= +============ -Here is a step by step plan on how to install Read the Docs. -It will get you to a point of having a local running instance. +Here is a step by step plan on how to install Read the Docs. It will get you to +a point of having a local running instance. .. warning:: @@ -13,11 +13,11 @@ It will get you to a point of having a local running instance. steps are performed using Python 2.7. -First, obtain `Python 2.7`_ and virtualenv_ if you do not already have them. Using a -virtual environment will make the installation easier, and will help to avoid -clutter in your system-wide libraries. You will also need Git_ in order to -clone the repository. If you plan to import Python 3 project to your RTD then you'll -need to install Python 3 with virtualenv in your system as well. +First, obtain `Python 2.7`_ and virtualenv_ if you do not already have them. +Using a virtual environment will make the installation easier, and will help to +avoid clutter in your system-wide libraries. You will also need Git_ in order +to clone the repository. If you plan to import Python 3 project to your RTD +then you'll need to install Python 3 with virtualenv in your system as well. .. _Python 2.7: http://www.python.org/ @@ -78,7 +78,8 @@ need to install Python 3 with virtualenv in your system as well. sudo apt-get install redis-server -You will need to verify that your pip version is higher than 1.5 you can do this as such:: +You will need to verify that your pip version is higher than 1.5 you can do +this as such:: pip --version @@ -140,11 +141,11 @@ you're serving on (i.e. ``runserver 0.0.0.0:8080``) match the port defined in ``PRODUCTION_DOMAIN``. You can utilize ``local_settings.py`` to modify this. (By default, it's ``localhost:8000``) -While the webserver is running, you can build documentation for the latest version of -a project called 'pip' with the ``update_repos`` command. You can replace 'pip' -with the name of any added project:: +While the webserver is running, you can build documentation for the latest +version of a project called 'pip' with the ``update_repos`` command. You can +replace 'pip' with the name of any added project:: - python manage.py update_repos pip + python manage.py update_repos pip What's available ---------------- From d907524ddec69c2530324d9c6cc7011830a209d8 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:41:13 -0500 Subject: [PATCH 05/19] Remove note about changing README to index --- docs/builds.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/builds.rst b/docs/builds.rst index ec36a3e32a4..3eee6afaea2 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -37,8 +37,6 @@ We will look inside a ``doc`` or ``docs`` directory first, and then look within your entire project. Then Sphinx will build any files with an ``.rst`` extension. -If you have a ``README.rst``, -it will be transformed into an ``index.rst`` automatically. Mkdocs ~~~~~~ @@ -50,11 +48,9 @@ we will generate one for you. We will look inside a ``doc`` or ``docs`` directory first, and then default to the top-level of your documentation. -Then Mkdocs will build any files with an ``.md`` extension. -If you have a ``README.md``, -it will be transformed into an ``index.md`` automatically. -As MkDocs doesn't support automatic PDF generation, -Read the Docs cannot create a PDF version of your documentation with the *Mkdocs* option. +Then Mkdocs will build any files with an ``.md`` extension. As MkDocs doesn't +support automatic PDF generation, Read the Docs cannot create a PDF version of +your documentation with the *Mkdocs* option. Understanding what's going on ----------------------------- From 9cf17423704481531fbe679903efbdc1ff255781 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:42:18 -0500 Subject: [PATCH 06/19] Wrap to 80 characters --- docs/builds.rst | 91 +++++++++++++++++++++++++++++++------------------ 1 file changed, 58 insertions(+), 33 deletions(-) diff --git a/docs/builds.rst b/docs/builds.rst index 3eee6afaea2..5f51b6bcca3 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -15,38 +15,38 @@ Our current build limits are: We can increase build limits on a per-project basis, if you provide a good reason your documentation needs more resources. -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. +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:2.0`` docker image as our default image. +Currently in production we're using the ``readthedocs/build:2.0`` 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, +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 ~~~~~~ -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. +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. Then Sphinx will build any files with an ``.rst`` extension. Mkdocs ~~~~~~ -When you choose *Mkdocs* as your *Documentation Type*, -we will first look for a ``mkdocs.yml`` 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 default to the top-level of your documentation. +When you choose *Mkdocs* as your *Documentation Type*, we will first look for a +``mkdocs.yml`` 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 default to the top-level of your documentation. Then Mkdocs will build any files with an ``.md`` extension. As MkDocs doesn't support automatic PDF generation, Read the Docs cannot create a PDF version of @@ -55,17 +55,27 @@ your documentation with the *Mkdocs* option. Understanding what's going on ----------------------------- -Understanding how Read the Docs builds your project will help you with debugging the problems you have with the site. It should also allow you to take advantage of certain things that happen during the build process. +Understanding how Read the Docs builds your project will help you with +debugging the problems you have with the site. It should also allow you to take +advantage of certain things that happen during the build process. -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 projects configuration. +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 projects 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. -If you have the *Install Project* option enabled, we will run ``setup.py install`` on your package, installing it into a virtual environment. You can also define additional packages to install with the *Requirements File* option. +If you have the *Install Project* option enabled, we will run ``setup.py +install`` on your package, installing it into a virtual environment. You can +also define additional packages to install with the *Requirements File* option. -When we build your documentation, we run `sphinx-build -b html . _build/html`, where `html` would be replaced with the correct backend. We also create man pages and pdf's automatically based on your project. +When we build your documentation, we run `sphinx-build -b html . _build/html`, +where `html` would be replaced with the correct backend. We also create man +pages and pdf's automatically based on your project. -Then these files are copied across to our application servers from the build server. Once on the application servers, they are served from nginx. +Then these files are copied across to our application servers from the build +server. Once on the application servers, they are served from nginx. An example in code: @@ -84,16 +94,20 @@ 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. +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. Packages installed in the build environment ------------------------------------------- -The build server does 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. We currently have the following libraries installed: +The build server does 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. We currently have the +following libraries installed: * doxygen * LaTeX (texlive-full) @@ -106,11 +120,17 @@ The build server does have a select number of C libraries installed, because the 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. +.. 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 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 :doc:`api/doc_builder` API explains the higher level parts of the API that you need to implement. A basic run goes something like this:: +The :doc:`api/doc_builder` API explains the higher level parts of the API that +you need to implement. A basic run goes something like this:: backend = get_backend(project.documentation_type) if force: @@ -123,12 +143,17 @@ The :doc:`api/doc_builder` API explains the higher level parts of the API that y 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. +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: +The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment +variables when building your documentation: +-------------------------+--------------------------------------------------+----------------------+ | Environment variable | Description | Example value | From 484377bc36f09a1df3c34f370c2be4d89867bd15 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:44:53 -0500 Subject: [PATCH 07/19] Fix typo --- docs/faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.rst b/docs/faq.rst index efe7128d1f7..5b9d687defa 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -23,7 +23,7 @@ as it `breaks the internet `_. Help, my build passed but my documentation page is 404 Not Found! ----------------------------------------------------------------- -This often happens becuase you don't have an `index.html` file being generated. +This often happens because you don't have an `index.html` file being generated. Make sure you have one of the following files: * `index.rst` From 6f86eecf8b54df44a8afdd1c9d2d8bb2417fb2c4 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 9 Jan 2018 17:49:32 -0500 Subject: [PATCH 08/19] Wrap to 80 characters --- docs/faq.rst | 51 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 13 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 5b9d687defa..2ee5467f39e 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -4,9 +4,15 @@ Frequently Asked Questions My project isn't building with autodoc -------------------------------------- -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, 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. -If you are still seeing errors because of C library dependencies, please see the below section about that. +If you are still seeing errors because of C library dependencies, please see +the below section about that. How do I change my slug (the URL your docs are served at)? ---------------------------------------------------------- @@ -57,14 +63,18 @@ environment, and will be set to ``True`` when building on RTD:: {% endif %} I get import errors on libraries that depend on C modules ----------------------------------------------------------- +--------------------------------------------------------- .. note:: Another use case for this is when you have a module with a C extension. -This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports. +This happens because our build system doesn't have the dependencies for +building your project. This happens with things like libevent and mysql, and +other python things that depend on C libraries. We can't support installing +random C binaries on our system, so there is another way to fix these imports. -You can mock out the imports for these modules in your ``conf.py`` with the following snippet:: +You can mock out the imports for these modules in your ``conf.py`` with the +following snippet:: import sys from unittest.mock import MagicMock @@ -79,12 +89,15 @@ You can mock out the imports for these modules in your ``conf.py`` with the foll Of course, replacing `MOCK_MODULES` with the modules that you want to mock out. -.. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier versions install the ``mock`` library - from PyPI with (ie ``pip install mock``) and replace the above import:: +.. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier + versions install the ``mock`` library from PyPI with (ie ``pip install + mock``) and replace the above import:: from mock import Mock as MagicMock -If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment. +If such libraries are installed via ``setup.py``, you also will need to remove +all the C-dependent libraries from your ``install_requires`` in the RTD +environment. `Client Error 401` when building documentation ---------------------------------------------- @@ -133,12 +146,19 @@ You can add subprojects in the Admin section for your project. 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. 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 :), 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 --------------------------------------------- @@ -149,12 +169,15 @@ 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. +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: http://disqus.com/ .. _sphinxcontrib-disqus: https://pypi.python.org/pypi/sphinxcontrib-disqus @@ -219,4 +242,6 @@ file* field. 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/rtfd/readthedocs.org/commits/rel +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/rtfd/readthedocs.org/commits/rel From ec70855a5f02a4fbac2fc81986756d8d1e8a28b0 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 11 Jan 2018 21:59:31 -0500 Subject: [PATCH 09/19] Add styleguide for docs --- docs/docs.rst | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/docs.rst b/docs/docs.rst index 1cf84eb60f6..71d687812bd 100644 --- a/docs/docs.rst +++ b/docs/docs.rst @@ -10,4 +10,29 @@ You can build the docs by installing ``Sphinx`` and running:: # in the docs directory make html -Let us know if you have any questions or want to contribute to the documentation. +Please follow these guidelines when updating our docs. +Let us know if you have any questions or if something isn't clear. + +The brand +--------- + +We are called **Read the Docs**. +The *the* is not capitalized. + +We do however use the acronym **RTD**. + +Titles +------ + +For page titles, or Heading1 as they are sometimes called, we use title-case. + +If the page includes multiple sub-headings (H2, H3), +we usually use sentence-case unless the titles include terminology that is supposed to be capitalized. + +Content +------- + +* Do not break the content across multiple lines at 80 characters, + but rather broken them on semantic meaning (e.g. periods or commas). +* If you are cross-referencing to a different page within our website, + use the ``doc`` directive and not a hyperlink. From 344ec5cbad27b1e49180e8138df053cd6158a48d Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 23 Jan 2018 15:54:05 -0500 Subject: [PATCH 10/19] Revert "Wrap to 80 characters" This reverts commit 6e59fd0065fe5def2dda5288637523a1658de145. --- docs/install.rst | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 6fbfbf7d015..cf7c3321dc7 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,10 +1,10 @@ .. _installing-read-the-docs: Installation -============ +============= -Here is a step by step plan on how to install Read the Docs. It will get you to -a point of having a local running instance. +Here is a step by step plan on how to install Read the Docs. +It will get you to a point of having a local running instance. .. warning:: @@ -13,11 +13,11 @@ a point of having a local running instance. steps are performed using Python 2.7. -First, obtain `Python 2.7`_ and virtualenv_ if you do not already have them. -Using a virtual environment will make the installation easier, and will help to -avoid clutter in your system-wide libraries. You will also need Git_ in order -to clone the repository. If you plan to import Python 3 project to your RTD -then you'll need to install Python 3 with virtualenv in your system as well. +First, obtain `Python 2.7`_ and virtualenv_ if you do not already have them. Using a +virtual environment will make the installation easier, and will help to avoid +clutter in your system-wide libraries. You will also need Git_ in order to +clone the repository. If you plan to import Python 3 project to your RTD then you'll +need to install Python 3 with virtualenv in your system as well. .. _Python 2.7: http://www.python.org/ @@ -78,8 +78,7 @@ then you'll need to install Python 3 with virtualenv in your system as well. sudo apt-get install redis-server -You will need to verify that your pip version is higher than 1.5 you can do -this as such:: +You will need to verify that your pip version is higher than 1.5 you can do this as such:: pip --version @@ -141,11 +140,11 @@ you're serving on (i.e. ``runserver 0.0.0.0:8080``) match the port defined in ``PRODUCTION_DOMAIN``. You can utilize ``local_settings.py`` to modify this. (By default, it's ``localhost:8000``) -While the webserver is running, you can build documentation for the latest -version of a project called 'pip' with the ``update_repos`` command. You can -replace 'pip' with the name of any added project:: +While the webserver is running, you can build documentation for the latest version of +a project called 'pip' with the ``update_repos`` command. You can replace 'pip' +with the name of any added project:: - python manage.py update_repos pip + python manage.py update_repos pip What's available ---------------- From 8c46050c71cfe5a887bacd9efd210f57a596eb0f Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 23 Jan 2018 15:54:36 -0500 Subject: [PATCH 11/19] Revert "Wrap to 80 characters" This reverts commit 9cf17423704481531fbe679903efbdc1ff255781. --- docs/builds.rst | 91 ++++++++++++++++++------------------------------- 1 file changed, 33 insertions(+), 58 deletions(-) diff --git a/docs/builds.rst b/docs/builds.rst index 5f51b6bcca3..3eee6afaea2 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -15,38 +15,38 @@ Our current build limits are: We can increase build limits on a per-project basis, if you provide a good reason your documentation needs more resources. -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. +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:2.0`` docker image -as our default image. +Currently in production we're using the ``readthedocs/build:2.0`` 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, +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 ~~~~~~ -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. +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. Then Sphinx will build any files with an ``.rst`` extension. Mkdocs ~~~~~~ -When you choose *Mkdocs* as your *Documentation Type*, we will first look for a -``mkdocs.yml`` 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 default to the top-level of your documentation. +When you choose *Mkdocs* as your *Documentation Type*, +we will first look for a ``mkdocs.yml`` 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 default to the top-level of your documentation. Then Mkdocs will build any files with an ``.md`` extension. As MkDocs doesn't support automatic PDF generation, Read the Docs cannot create a PDF version of @@ -55,27 +55,17 @@ your documentation with the *Mkdocs* option. Understanding what's going on ----------------------------- -Understanding how Read the Docs builds your project will help you with -debugging the problems you have with the site. It should also allow you to take -advantage of certain things that happen during the build process. +Understanding how Read the Docs builds your project will help you with debugging the problems you have with the site. It should also allow you to take advantage of certain things that happen during the build process. -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 projects configuration. +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 projects 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. -If you have the *Install Project* option enabled, we will run ``setup.py -install`` on your package, installing it into a virtual environment. You can -also define additional packages to install with the *Requirements File* option. +If you have the *Install Project* option enabled, we will run ``setup.py install`` on your package, installing it into a virtual environment. You can also define additional packages to install with the *Requirements File* option. -When we build your documentation, we run `sphinx-build -b html . _build/html`, -where `html` would be replaced with the correct backend. We also create man -pages and pdf's automatically based on your project. +When we build your documentation, we run `sphinx-build -b html . _build/html`, where `html` would be replaced with the correct backend. We also create man pages and pdf's automatically based on your project. -Then these files are copied across to our application servers from the build -server. Once on the application servers, they are served from nginx. +Then these files are copied across to our application servers from the build server. Once on the application servers, they are served from nginx. An example in code: @@ -94,20 +84,16 @@ 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. +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. Packages installed in the build environment ------------------------------------------- -The build server does 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. We currently have the -following libraries installed: +The build server does 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. We currently have the following libraries installed: * doxygen * LaTeX (texlive-full) @@ -120,17 +106,11 @@ following libraries installed: 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. +.. 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 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 :doc:`api/doc_builder` API explains the higher level parts of the API that -you need to implement. A basic run goes something like this:: +The :doc:`api/doc_builder` API explains the higher level parts of the API that you need to implement. A basic run goes something like this:: backend = get_backend(project.documentation_type) if force: @@ -143,17 +123,12 @@ you need to implement. A basic run goes something like this:: 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. +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: +The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment variables when building your documentation: +-------------------------+--------------------------------------------------+----------------------+ | Environment variable | Description | Example value | From 4cc4d46d476ade8c031a4c634a0ddaacd9cee897 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 23 Jan 2018 15:54:57 -0500 Subject: [PATCH 12/19] Revert "Wrap to 80 characters" This reverts commit 6f86eecf8b54df44a8afdd1c9d2d8bb2417fb2c4. --- docs/faq.rst | 51 +++++++++++++-------------------------------------- 1 file changed, 13 insertions(+), 38 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 2ee5467f39e..5b9d687defa 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -4,15 +4,9 @@ Frequently Asked Questions My project isn't building with autodoc -------------------------------------- -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, 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. -If you are still seeing errors because of C library dependencies, please see -the below section about that. +If you are still seeing errors because of C library dependencies, please see the below section about that. How do I change my slug (the URL your docs are served at)? ---------------------------------------------------------- @@ -63,18 +57,14 @@ environment, and will be set to ``True`` when building on RTD:: {% endif %} I get import errors on libraries that depend on C modules ---------------------------------------------------------- +---------------------------------------------------------- .. note:: Another use case for this is when you have a module with a C extension. -This happens because our build system doesn't have the dependencies for -building your project. This happens with things like libevent and mysql, and -other python things that depend on C libraries. We can't support installing -random C binaries on our system, so there is another way to fix these imports. +This happens because our build system doesn't have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can't support installing random C binaries on our system, so there is another way to fix these imports. -You can mock out the imports for these modules in your ``conf.py`` with the -following snippet:: +You can mock out the imports for these modules in your ``conf.py`` with the following snippet:: import sys from unittest.mock import MagicMock @@ -89,15 +79,12 @@ following snippet:: Of course, replacing `MOCK_MODULES` with the modules that you want to mock out. -.. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier - versions install the ``mock`` library from PyPI with (ie ``pip install - mock``) and replace the above import:: +.. Tip:: The library ``unittest.mock`` was introduced on python 3.3. On earlier versions install the ``mock`` library + from PyPI with (ie ``pip install mock``) and replace the above import:: from mock import Mock as MagicMock -If such libraries are installed via ``setup.py``, you also will need to remove -all the C-dependent libraries from your ``install_requires`` in the RTD -environment. +If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment. `Client Error 401` when building documentation ---------------------------------------------- @@ -146,19 +133,12 @@ You can add subprojects in the Admin section for your project. 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. 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 :), 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 --------------------------------------------- @@ -169,15 +149,12 @@ 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. +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: http://disqus.com/ .. _sphinxcontrib-disqus: https://pypi.python.org/pypi/sphinxcontrib-disqus @@ -242,6 +219,4 @@ file* field. 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/rtfd/readthedocs.org/commits/rel +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/rtfd/readthedocs.org/commits/rel From b2f665612b6c7b0a8ad8cafec4de89fc3612a196 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 23 Jan 2018 15:56:40 -0500 Subject: [PATCH 13/19] Fix header --- docs/faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.rst b/docs/faq.rst index 5b9d687defa..e7fdff31ee4 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -57,7 +57,7 @@ environment, and will be set to ``True`` when building on RTD:: {% endif %} I get import errors on libraries that depend on C modules ----------------------------------------------------------- +--------------------------------------------------------- .. note:: Another use case for this is when you have a module with a C extension. From 99ced33dfff617b101088465bd2f70257f7efacf Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 23 Jan 2018 15:57:28 -0500 Subject: [PATCH 14/19] Fix header --- docs/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install.rst b/docs/install.rst index cf7c3321dc7..271571117a2 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,7 +1,7 @@ .. _installing-read-the-docs: Installation -============= +============ Here is a step by step plan on how to install Read the Docs. It will get you to a point of having a local running instance. From a2302785742ae1059b9f80b13d67997880f8353d Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 23 Jan 2018 15:58:27 -0500 Subject: [PATCH 15/19] Fix indentation --- docs/install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install.rst b/docs/install.rst index 271571117a2..85405ef0ec5 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -144,7 +144,7 @@ While the webserver is running, you can build documentation for the latest versi a project called 'pip' with the ``update_repos`` command. You can replace 'pip' with the name of any added project:: - python manage.py update_repos pip + python manage.py update_repos pip What's available ---------------- From db2c67ac51c73d0cf5a326d62d2408107cd93992 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 23 Jan 2018 16:07:05 -0500 Subject: [PATCH 16/19] Style --- docs/builds.rst | 6 +++--- docs/install.rst | 10 ++++------ 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/builds.rst b/docs/builds.rst index 3eee6afaea2..6b0b08fe726 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -48,9 +48,9 @@ we will generate one for you. We will look inside a ``doc`` or ``docs`` directory first, and then default to the top-level of your documentation. -Then Mkdocs will build any files with an ``.md`` extension. As MkDocs doesn't -support automatic PDF generation, Read the Docs cannot create a PDF version of -your documentation with the *Mkdocs* option. +Then MkDocs will build any files with a ``.md`` extension. +As MkDocs doesn't support automatic PDF generation, +Read the Docs cannot create a PDF version of your documentation with the *Mkdocs* option. Understanding what's going on ----------------------------- diff --git a/docs/install.rst b/docs/install.rst index 85405ef0ec5..1eb7db9424d 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -155,9 +155,7 @@ will be able to log in and view the `dashboard Date: Tue, 23 Jan 2018 19:55:46 -0500 Subject: [PATCH 17/19] More style changes --- docs/install.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 1eb7db9424d..ad644d1c946 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -149,8 +149,8 @@ with the name of any added project:: What's available ---------------- -After registering with the site (or creating yourself a superuser account), you -will be able to log in and view the `dashboard `_. +After registering with the site (or creating yourself a superuser account), +you will be able to log in and view the `dashboard `_. Importing your docs ^^^^^^^^^^^^^^^^^^^ From 57fd486f9593a836748980ba656e40807ce01780 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 15 Feb 2018 20:25:42 -0500 Subject: [PATCH 18/19] Rename Mkdocs to MkDocs --- docs/builds.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/builds.rst b/docs/builds.rst index 6b0b08fe726..d73da5c01d2 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -38,7 +38,7 @@ and then look within your entire project. Then Sphinx will build any files with an ``.rst`` extension. -Mkdocs +MkDocs ~~~~~~ When you choose *Mkdocs* as your *Documentation Type*, From c870ceb3d735c48092bea30065279d7ff01b2a35 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 15 Feb 2018 20:37:51 -0500 Subject: [PATCH 19/19] Fix grammar --- docs/docs.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs.rst b/docs/docs.rst index 71d687812bd..81ea77a227c 100644 --- a/docs/docs.rst +++ b/docs/docs.rst @@ -11,7 +11,7 @@ You can build the docs by installing ``Sphinx`` and running:: make html Please follow these guidelines when updating our docs. -Let us know if you have any questions or if something isn't clear. +Let us know if you have any questions or something isn't clear. The brand --------- @@ -33,6 +33,7 @@ Content ------- * Do not break the content across multiple lines at 80 characters, - but rather broken them on semantic meaning (e.g. periods or commas). + but rather break them on semantic meaning (e.g. periods or commas). + Read more about this `here `_. * If you are cross-referencing to a different page within our website, use the ``doc`` directive and not a hyperlink.