readthedocs · benjaoming · Feb 24, 2023 · Feb 21, 2023 · Feb 24, 2023 · Feb 24, 2023
@@ -12,7 +12,7 @@ to get a working copy of the Read the Docs repository locally.
 
 .. TODO: update to match the new ext-theme
 
-Style Catalog
+Style catalog
 -------------
 
 Once you have RTD running locally, you can open ``http://localhost:8000/style-catalog/``
@@ -24,7 +24,7 @@ This way you can quickly get started writing HTML -- or if you're
 modifying existing styles you can get a quick idea of how things
 will change site-wide.
 
-Readthedocs.org Changes
+Readthedocs.org changes
 -----------------------
 
 Styles for the primary RTD site are located in ``media/css`` directory.
@@ -44,7 +44,7 @@ There's not a hard browser range, but your design changes should work reasonably
 browsers, IE8+ -- that's not to say it needs to be pixel-perfect in older browsers! Just avoid
 making changes that render older browsers utterly unusable (or provide a sane fallback).
 
-Brand Guidelines
+Brand guidelines
 ----------------
 
 Find our branding guidelines in our guidelines documentation: https://read-the-docs-guidelines.readthedocs-hosted.com.

@@ -1,5 +1,5 @@
 ======================
-API v3 Design Document
+API v3 design document
 ======================
 
 This document describes the design,

@@ -1,4 +1,4 @@
-Build Images
+Build images
 ============
 
 This document describes how Read the Docs uses the `Docker Images`_ and how they are named.

@@ -1,4 +1,4 @@
-Future Builder
+Future builder
 ==============
 
 .. contents::

@@ -1,4 +1,4 @@
-In Doc Search UI
+In-doc search UI
 ================
 
 Giving readers the ability to easily search the information
@@ -24,34 +24,34 @@ The final result may look something like this:
     Short demo
 
 
-Goals And Non-Goals
+Goals And non-Goals
 -------------------
 
-Project Goals
-++++++++++++++
+Project goals
++++++++++++++
 
 * Support a search-as-you-type/autocomplete interface.
 * Support across all (or virtually all) Sphinx themes.
 * Support for the JavaScript user experience down to IE11 or graceful degradation where we can't support it.
 * Project maintainers should have a way to opt-in/opt-out of this feature.
 * (Optional) Project maintainers should have the flexibility to change some of the styles using custom CSS and JS files.
 
-Non-Goals
-++++++++++
+Non-goals
++++++++++
 
 * For the initial release, we are targeting only Sphinx documentations
   as we don't index MkDocs documentations to our Elasticsearch index.
 
 
-Existing Search Implementation
+Existing search implementation
 ------------------------------
 
 We have a detailed documentation explaining the underlying architecture of our search backend
 and how we index documents to our Elasticsearch index.
 You can read about it :doc:`here </server-side-search>`.
 
 
-Proposed Architecture for In-Doc Search UI
+Proposed architecture for in-doc search UI
 ------------------------------------------
 
 Frontend
@@ -69,7 +69,7 @@ This will provide us some advantages over using any third party library:
 * Performance benefits.
 
 
-Proposed Architecture
+Proposed architecture
 ~~~~~~~~~~~~~~~~~~~~~
 
 We plan to select the search bar, which is present in every theme,
@@ -125,7 +125,7 @@ Edge NGram Tokenizer
   * Requires greater disk space.
 
 
-Completion Suggester
+Completion suggester
 ~~~~~~~~~~~~~~~~~~~~
 
 * Pros
@@ -164,7 +164,7 @@ Milestones
 +-----------------------------------------------------------------------------------+------------------+
 
 
-Open Questions
+Open questions
 ++++++++++++++
 
 * Should we rely on jQuery, any third party library or pure vanilla JavaScript?

@@ -1,4 +1,4 @@
-Design Documents
+Design documents
 ================
 
 This is where we outline the design of major parts of our project.
@@ -7,7 +7,7 @@ but we hope to write more of them over time.
 
 .. warning::
 
-   These documents may not match the final implementation, or may be out of date. 
+   These documents may not match the final implementation, or may be out of date.
 
 .. toctree::
    :maxdepth: 1

@@ -1,4 +1,4 @@
-Design of Pull Request Builder
+Design of pull request builder
 ==============================
 
 Background
@@ -25,7 +25,7 @@ Scope
 - Triggering Builds on new commits on a PR
 - Status reporting to Github
 
-Fetching Data from Pull Requests
+Fetching data from pull requests
 --------------------------------
 
 We already get Pull request events from Github webhooks.
@@ -34,7 +34,7 @@ when a ``pull_request`` event is triggered we can fetch the data of that pull re
 We can fetch the pull request by doing something similar to travis-ci.
 ie: ``git fetch origin +refs/pull/<pr_number>/merge:``
 
-Modeling Pull Requests as a Type of Version
+Modeling pull requests as a type of version
 -------------------------------------------
 
 Pull requests can be Treated as a Type of Temporary ``Version``.
@@ -52,34 +52,34 @@ We can then use ``Build.internal.all()`` to get all regular version builds,
 ``Build.external.all()`` to get all PR version builds.
 
 
-Excluding PR Versions from Elasticsearch Indexing
+Excluding PR versions from Elasticsearch indexing
 -------------------------------------------------
 
 We should exclude to PR Versions from being Indexed to Elasticsearch.
 We need to update the queryset to exclude PR Versions.
 
-Adding a PR Builds Tab in the Project Dashboard
+Adding a PR builds tab in the project dashboard
 -----------------------------------------------
 
 We can add a Tab in the project dashboard that will listout the PR Builds of that project.
 We can name it ``PR Builds``.
 
-Creating Versions for Pull Requests
+Creating versions for pull requests
 -----------------------------------
 
 If the Github webhook event is ``pull_request`` and action is ``opened``,
 this means a pull request was opened in the projects repository.
 We can create a ``Version`` from the Payload data and trigger a initial build for the version.
 A version will be created whenever RTD receives an event like this.
 
-Triggering Build for New Commits in a Pull Request
+Triggering build for new commits in a pull request
 --------------------------------------------------
 
 We might want to trigger a new build for the PR version if there is a new commit on the PR.
 If the Github webhook event is ``pull_request`` and action is ``synchronize``,
 this means a new commit was added to the pull request.
 
-Status Reporting to Github
+Status reporting to GitHub
 --------------------------
 
 We could send build status reports to Github. We could send if the build was Successful or Failed.
@@ -101,21 +101,21 @@ Sending the status report would be something like this:
        "context": "continuous-documentation/read-the-docs"
    }
 
-Storing Pull Request Docs
+Storing pull request docs
 -------------------------
 
 We need to think about how and where to store data after a PR Version build is finished.
 We can store the data in a blob storage.
 
-Excluding PR Versions from Search Engines
+Excluding PR versions from search engines
 -----------------------------------------
 
 We should Exclude the PR Versions from Search Engines,
 because it might cause problems for RTD users.
 As users might land to a pull request doc but not the original Project Docs.
 This will cause confusion for the users.
 
-Serving PR Docs
+Serving PR docs
 ---------------
 
 We need to think about how we want to serve the PR Docs.
@@ -136,13 +136,13 @@ We might want to have a way to show that if this is a PR Build on the Footer.
 - For regular project docs we should remove the PR Versions from the version list of the Footer.
 - We might want to send ``is_pr`` data with the Footer API response.
 
-Adding Warning Banner to Docs
+Adding warning banner to Docs
 -----------------------------
 
 We need to add a warning banner to the PR Version Docs to let the users know that this is a Draft/PR version.
 We can use a sphinx extension that we will force to install on the PR Versions to add the warning banner.
 
-Related Issues
+Related issues
 --------------
 
 - `Autobuild Docs for Pull Requests`_

@@ -1,4 +1,4 @@
-Privacy Levels
+Privacy levels
 ==============
 
 This document describes how to handle and unify privacy levels
@@ -156,7 +156,7 @@ Public project (community)
   Users didn't want to show this version to their users yet or they were testing something.
   This can be solved with the pull request builder feature and the ``hidden`` setting.
   We migrate those to public with the ``hidden`` setting.
-  If we are worried about leaking anything from the version, we can email users before doing the change. 
+  If we are worried about leaking anything from the version, we can email users before doing the change.
 
 Protected project (community)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -1,6 +1,6 @@
-======================================
- Refactor ``RemoteRepository`` object
-======================================
+====================================
+Refactor ``RemoteRepository`` object
+====================================
 
 
 This document describes the current usage of ``RemoteRepository`` objects and proposes a new normalized modeling.
@@ -18,7 +18,7 @@ Goals
 * Do not disconnect ``Project`` and ``RemoteRepository`` when a user delete/disconnects their account.
 
 
-Non-Goals
+Non-goals
 =========
 
 * Keep ``RemoteRepository`` in sync with GitHub repositories.
@@ -31,7 +31,7 @@ Non-Goals
    They are just outside the scope of this document.
 
 
-Current Implementation
+Current implementation
 ======================
 
 When a user connect their account to a social account, we create a
@@ -78,7 +78,7 @@ Where ``RemoteRepository`` is used?
 .. _Send build status: https://github.com/readthedocs/readthedocs.org/blob/56253cb786945c9fe53a034a4433f10672ae8a4f/readthedocs/projects/tasks.py#L1852-L1956
 
 
-New Normalized Implementation
+New normalized implementation
 =============================
 
 The ``ManyToMany`` relation ``RemoteRepository.users`` will be changed to be ``ManyToMany(through='RemoteRelation')``
@@ -109,7 +109,7 @@ We can get the list of ``Project`` where a user as access:
    Project.objects.filter(remote_repository__in=admin_remote_repositories)
 
 
-Rollout Plan
+Rollout plan
 ============
 
 Due the constraints we have in the ``RemoteRepository`` table and its size,

@@ -1,4 +1,4 @@
-Allow Installation of System Packages
+Allow installation of system packages
 =====================================
 
 Currently we don't allow executing arbitrary commands in the build process.

@@ -1,4 +1,4 @@
-Collect Data About Builds
+Collect data about builds
 =========================
 
 We may want to take some decisions in the future about deprecations and supported versions.

@@ -1,4 +1,4 @@
-YAML Configuration File
+YAML configuration file
 =======================
 
 Background
@@ -16,14 +16,14 @@ Scope
 - Proper documentation for the end user
 - Allow to specify the spec's version used on the YAML file
 - Collect/show metadata about the YAML file and build configuration
-- Promote the adoption of the configuration file 
+- Promote the adoption of the configuration file
 
 RTD settings
 ------------
 
 No all the RTD settings are applicable to the YAML file,
 others are applicable for each build (or version),
-and others for the global project. 
+and others for the global project.
 
 Not applicable settings
 ~~~~~~~~~~~~~~~~~~~~~~~

@@ -1,4 +1,4 @@
-Building and Contributing to Documentation
+Building and contributing to documentation
 ==========================================
 
 As one might expect,

@@ -1,4 +1,4 @@
-Front End Development
+Front-end development
 =====================
 
 Background
@@ -52,7 +52,7 @@ may change, so that assets are compiled before deployment, however as our front
 end assets are in a state of flux, it's easier to keep absolute sources checked
 in.
 
-Getting Started
+Getting started
 ---------------
 
 You will need to follow our :doc:`guide to install a development Read the Docs instance </install>` first.
@@ -72,7 +72,7 @@ make sure to check in both files under ``static`` and ``static-src``,
 and commit those.
 
 
-Making Changes
+Making changes
 --------------
 
 If you are creating a new library, or a new library entry point, make sure to
@@ -93,7 +93,7 @@ If merging several branches with JavaScript changes, it's important to do a
 final post-merge bundle. Follow the steps above to rebundle the libraries, and
 check in any changed libraries.
 
-JavaScript Bundles
+JavaScript bundles
 ------------------
 
 There are several components to our bundling scheme:

@@ -1,4 +1,4 @@
-gVisor Installation
+gVisor installation
 ===================
 
 You can mostly get by just following installation instructions in the `gVisor

@@ -1,4 +1,4 @@
-Development Guides
+Development guides
 ==================
 
 These are guides to aid local development and common development procedures.