Outline Contribute

docs/source/contribute/documentation/docs-pr.rst

@@ -0,0 +1,66 @@
+========================
+Issues and Pull Requests
+========================
+
+Any documentation contribution, no matter how small, is made as a pull request (PR) on `our GitHub <https://github.com/NASA-AMMOS/aerie>`_.
+You can use a client, the Web UI, or the command line to manage your PRs.
+
+Issue assignment
+================
+
+The Aerie repository has `an issues page on GitHub <https://github.com/NASA-AMMOS/aerie/issues>`_.
+Doc issues are labeled with a ``documentation`` label.
+Please do not work on issues that are not assigned to you.
+This avoids working on something someone else is working on.
+Also, if there is an issue with any guide and the issue does not exist, please create an issue so it can be tracked.
+
+Guidelines for branch names
+===========================
+
+If you are providing documentation alongside new code, prefix the name of your branch with ``feature/AERIE-[Issue Number]--``.
+
+If you are only providing documentation, prefix the name of your branch with ``docs/AERIE-[Issue Number]--``.
+
+
+Previewing local changes
+========================
+
+Before submitting docs changes, we ask that you build them first locally. To do so, you will need:
+
+* `Python 3.7 <https://www.python.org/downloads/>`_ or later.
+* `Poetry 1.12 <https://python-poetry.org/docs/master/>`_ or later.
+
+To preview your changes while you are working, run ``make preview`` from the command line in the ``docs`` directory.
+If you have previously run ``make preview``, it is recommended to run ``make clean`` first. Navigate to http://127.0.0.1:5500/.
+The site will automatically update as you work. Fix all warnings raised during the build.
+
+When you are finished making changes, run ``make clean`` and then ``make dirhtml-ext`` to ensure that the site will deploy.
+Once the site builds successfully without warnings, you may proceed to the next step.
+
+To check for broken links, run ``make clean && make dirhtml-ext`` then ``make linkcheck``.
+Once ``make linkcheck`` builds with the only broken links being those that reference ``localhost`` sites, you may proceed to open a PR.
+
+
+Submit a pull request (PR)
+==========================
+
+We expect that you are aware of how to submit a PR to GitHub. If you are not, please look at this `tutorial <https://docs.github.com/en/get-started/quickstart/hello-world>`_.
+When creating a PR, fill out the provided template.
+
+For Documentation PRs, the following guidelines apply:
+
+* Test the instructions against the product. For all tests you must use a clean, new install unless otherwise specified in the issue.
+* Make sure the PR renders with no errors and that make preview does not return any errors.
+* Cite the issue you are fixing in the PR comments and use screenshots to show changes in formatting.
+* In the subject line of the PR prepend the subject with ``[Aerie Issue Number]``.
+* Apply the ``documentation`` label to your PR.
+
+If you have any questions about the process, ask the maintainer of the project you're working on.
+
+Best practices for content submission
+=====================================
+
+* Always open an issue describing what you want to work on if one doesn't already exist.
+* Use GitHub search to see if there is someone else working on the issue already. Look at the open PRs.
+* Test the new / changed content using the make preview script. Confirm there are no compilation errors before submitting.
+* Give some text to your commit message. Explain why you did what you did. If you changed something in formatting, provide a before and after screenshot.

docs/source/contribute/documentation/examples/headings.rst

@@ -1,7 +1,7 @@
 Headings
 ========
 
-While Sphinx supports many layers of headings, at Scylla we try to keep the hierarchy limited to 4, excluding the title.
+While Sphinx supports many layers of headings, we try to keep the hierarchy limited to 4, excluding the title.
 If you have the need for a H4, chances are that you need to re-arrange the content.
 Watch the length of your text vs the markup. It must be at least as long as the text.
 It can be longer, but shorter will produce an error.

docs/source/contribute/documentation/examples/hero-box.rst

@@ -57,8 +57,8 @@ The ``hero-box`` directive supports the following options:
   * - ``image``
     - string
     -
-    - /_static/img/mascots/scylla-enterprise.svg
-    - Path to the image. The image should be located in the project's ``_static`` folder.
+    - /_static/img/logos/aerie-logo-light.svg
+    - Path to the image.
   * - ``search_box``
     - flag
     -
@@ -96,15 +96,15 @@ Using:
 
     .. hero-box::
         :title: Lorem Ipsum
-        :image: /_static/img/mascots/scylla-enterprise.svg
+        :image: /_static/img/logos/aerie-logo-light.svg
 
         Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 Results in:
 
 .. hero-box::
     :title: Lorem Ipsum
-    :image: /_static/img/mascots/scylla-enterprise.svg
+    :image: /_static/img/logos/aerie-logo-light.svg
 
     Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
@@ -138,7 +138,7 @@ Using:
 
     .. hero-box::
         :title: Lorem Ipsum
-        :image: /_static/img/mascots/scylla-enterprise.svg
+        :image: /_static/img/logos/aerie-logo-light.svg
         :button_icon: fa fa-github
         :button_url: #
         :button_text: Project Name
@@ -149,7 +149,7 @@ Results in:
 
 .. hero-box::
     :title: Lorem Ipsum
-    :image: /_static/img/mascots/scylla-enterprise.svg
+    :image: /_static/img/logos/aerie-logo-light.svg
     :button_icon: fa fa-github
     :button_url: #
     :button_text: Project Name

docs/source/contribute/documentation/examples/includes.rst

@@ -5,21 +5,7 @@ An include directive allows you to include the entire contents of one restructur
 This is the easiest way to control content re-use.
 
 When given an absolute path, the directive takes it as relative to the root of the source directory.
-It is Scylla practice to place global include files in the *rst_include* directory.
-
-For example, here are some very commonly used include statements:
-
-.. code-block:: none
-
-   .. include:: /rst_include/scylla-commands-stop-index.rst
-
-.. code-block:: none
-
-   .. include:: /rst_include/scylla-commands-start-index.rst
-
-.. code-block:: none
-
-   .. include:: /rst_include/scylla-commands-restart-index.rst
+It is Aerie practice to place global include files in the *rst_include* directory.
 
 Literal include
 ---------------
@@ -35,5 +21,5 @@ For example:
 
 Gets the ``conf.py`` file from the parent directory and displays the first 10 lines.
 
-.. literalinclude:: ../conf.py
+.. literalinclude:: ../../../conf.py
       :lines: 1-10

docs/source/contribute/documentation/examples/index.rst

@@ -54,6 +54,6 @@ In general, the main components to the markup of any document include:
   * :doc:`Tables <tables>`
   * :doc:`Tabs <tabs>`
   * :doc:`Text <text>`
-  * :doc:`Toc <toc>`
+  * :doc:`Table of Contents (TOC) <toc>`
   * :doc:`Topic box <topic-box>`
   * :doc:`Versions <versions>`

docs/source/contribute/documentation/examples/substitutions.rst

@@ -5,13 +5,14 @@ Substitutions are variables. They are declared in any document and defined in th
 
 .. caution:: Do not use substitutions in headings. The reason is the text that replaces the variable may be longer than the line that is over or below the text and this will produce an error.
 
-Default substitutions
+List of substitutions
 ---------------------
 
-Projects using the theme can use the following substitutions:
+Our theme can use the following substitutions:
 
 * ``|v|`` for |v|
 * ``|x|`` for |x|
+* ``|rst|`` for |rst|
 
 Substitutions within code blocks
 --------------------------------