Update walkthroughs

bioteam · May 29, 2024 · 08f8e5e · 08f8e5e
1 parent fc5b96a
commit 08f8e5e
Show file tree

Hide file tree

Showing 15 changed files with 194 additions and 22 deletions.
diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/guides/.DS_Store b/docs/guides/.DS_Store
diff --git a/docs/guides/images/.DS_Store b/docs/guides/images/.DS_Store
diff --git a/docs/guides/images/guide_add_new_section.png b/docs/guides/images/guide_add_new_section.png
diff --git a/docs/guides/images/layout_left.png b/docs/guides/images/layout_left.png
diff --git a/docs/guides/images/layout_left_toplevel.png b/docs/guides/images/layout_left_toplevel.png
diff --git a/docs/guides/images/layout_right.png b/docs/guides/images/layout_right.png
diff --git a/docs/guides/images/layout_top.png b/docs/guides/images/layout_top.png
diff --git a/docs/guides/index.rst b/docs/guides/index.rst
@@ -15,6 +15,7 @@ Guides
    :caption: Walkthroughs
 
    walkthrough_adding_new_tab
+   walkthrough_adding_new_section
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/guides/reference_glossary.rst b/docs/guides/reference_glossary.rst
@@ -7,7 +7,7 @@ Glossary
         Directives are special commands that can be embedded as text into an rST document.
         They can be used to dictate how content in the document gets formatted by Sphinx. 
 
-        For example, having this in a document:
+        For example this:
 
         .. code-block:: rst
 
@@ -21,9 +21,49 @@ Glossary
 
             content
 
+        Note the empty line between the declaration of the directive and its contents.
+
 
     rST
        reStructuredText is a plaintext markup language that Sphinx can use to generate documentation.
        This will be the standard way we write documentation in this project. Mardown is an alternative langauge.
 
        See this `cheat sheet <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`_ for the common markup used in rST files.
+
+    Root Index
+        The root index is the top-level index rooted in the :code:`docs/` folder located in your project.
+        This index contains a :term:`toctree` that specifies the tabs in the top navigation bar.
+
+    Role
+        A role is a type of annotation used in :term:`rST` documents to indicate special formatting.
+        Roles can be used inline with text. For example, :code:`\:code\:\`text\`` would evaluate to :code:`text`.
+
+        Sphinx has some `built-in roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_.
+        Extensions can also add new roles. For example, `sphinx-design <https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html>`_ adds roles for in-line badges and icons like this: :octicon:`report;1em;sd-text-info`.
+
+        A :term:`Directive` can also have roles associated with it, in which case they work as "options" or "parameters". 
+        For example, to add line numbers to a code block directive, you need to add the :code:`\:linenos\:` option below the declaration:
+
+        .. code-block::
+            :linenos:
+
+            .. code-block::
+                :linenos:
+
+                Example
+
+
+    toctree
+        toctree (Table of Contents Tree) is a kind of :term:`directive` that is used to specify how documents should be laid out.
+        Here's an example of the :term:`root index`:
+
+        .. code-block::
+
+            .. toctree::
+                :maxdepth: 1
+
+                guides/index
+                tab_2/index
+                tab_3/index
+
+
diff --git a/docs/guides/walkthrough_adding_new_section.rst b/docs/guides/walkthrough_adding_new_section.rst
@@ -0,0 +1,134 @@
+Modifying Sections
+===================
+
+.. admonition:: Use the Source!
+    :class: sidebar tip
+
+    If you look to the sidebar on the right, you will see a link called :code:`Show Source`.  
+    You can click on it to see the source :term:`rST` used to create the current page.
+
+It's often the case that you'll want to organize the contents of a tab (see :doc:`the previous walkthrough on adding a new tab <walkthrough_adding_new_tab>`).
+We'll be covering the following scenarios:
+
+1. How to add a new section
+2. How to add a sub-section (section nested in a section)
+
+Exploring the left navigation layout
+====================================
+For this walkthrough, we'll be using the layout of the :code:`Tab_2` tab to understand how sections are organized.
+
+.. figure:: images/layout_left_toplevel.png
+    :class: sd-border-2
+
+    The four "subject" documents with the arrows next to them are "top-level documents". 
+
+This layout relates to the file tree rooted at :code:`sphinx-documentation-demo/docs/tab_2`: 
+
+.. code-block::
+
+    📦tab_2
+    ┣ 📂subsection_1
+    ┃ ┣ 📜index.rst
+    ┃ ┣ 📜subsubject_1.rst
+    ┃ ┗ 📜subsubject_2.rst
+    ┣ 📂subsection_2
+    ┃ ┣ 📜index.rst
+    ┃ ┣ 📜subsubject_3.rst
+    ┃ ┗ 📜subsubject_4.rst
+    ┣ 📜index.rst
+    ┣ 📜subject_1.rst       <- top level
+    ┣ 📜subject_2.rst       <- top level
+    ┣ 📜subject_3.rst       <- top level
+    ┗ 📜subject_4.rst       <- top level
+
+The subjects with the arrows are "top level documents".
+
+Organizing Top-Level Sections
+-----------------------------
+So how does Sphinx know how to organize those top-level documents into **Section 1** and **Section 2**?
+
+Let's look at :code:`sphinx-documentation-demo/docs/tab_2/index.rst`:
+
+
+.. code-block::
+    :emphasize-lines: 3,11
+    :linenos:
+
+    .. toctree::
+        :maxdepth: 1
+        :caption: Section 1
+
+        subject_1
+        subsection_1/index
+        subject_2
+
+    .. toctree::
+        :maxdepth: 1
+        :caption: Section 2
+
+        subject_3
+        subject_4
+        subsection_2/index
+
+* There are two toctrees contained in this index.
+* Each toctree corresponds to a **section** within **Tab_2**
+
+  * The name of the section is determined by the :code:`\:caption\:` :term:`role` (see the two lines highlighted in yellow)
+* **subject_1** and **subject_2** belong to the first toctree ("Section 1")
+* **subject_3** and **subject_4** belong to the second toctree ("Section 2")
+
+
+Adding New Section
+==================
+A quick way to demonstrate adding a new section is by adding a new :term:`toctree` to the index at :code:`docs/tab_2/index.rst`.
+We will also move an existing document to the new section. 
+
+Change the toctrees in :code:`docs/tab_2/index.rst` to the following:
+
+.. code-block::
+    :emphasize-lines: 19,21
+    :linenos:
+
+    .. toctree::
+        :maxdepth: 1
+        :caption: Section 1
+
+        subject_1
+        subsection_1/index
+        subject_2
+
+    .. toctree::
+        :maxdepth: 1
+        :caption: Section 2
+
+        subject_3
+        subject_4
+        subsection_2/index
+
+    .. toctree::
+        :maxdepth: 1
+        :caption: My New Section
+
+        subject_4
+
+
+.. admonition:: Remember to build!
+    :class: sidebar warning
+
+    You need to use :code:`sphinx-build` or :code:`sphinx-autobuild` to build documentation before you notice any changes in the following steps.
+
+* The last :term:`toctree` is the new one added for this demonstration.
+* The first highlighted line will be the title of the section.
+* The second highlighted line will be the document (:code:`subject_4`) that's contained in this new section.
+
+  * Notice that you can have the same document in more than one section. Sphinx knows how to link to the same document.
+
+
+.. figure:: images/guide_add_new_section.png
+    :class: sd-border-2
+
+    You should notice a new section in Tab_2.
+
+Adding a New Subsection
+=======================
+A subsection is nested within an existing section. 
diff --git a/docs/guides/walkthrough_adding_new_tab.rst b/docs/guides/walkthrough_adding_new_tab.rst
@@ -1,13 +1,14 @@
-Adding New Tab
+Modifying Tabs
 ==============
 
 .. figure:: images/layout_top.png
     :class: sd-border-2
 
     This walkthrough will cover how to add new tabs to the top bar (highlighted in red).
 
+
 Find the Root Index
--------------------
+===================
 The :code:`index.rst` files contain :code:`toctrees` that specify what rST documents should be included in the layout.
 
 In this walkthrough, we will need to edit the **root index**, which is the first **index.rst** file you find in the docs folder located within the project directory:
@@ -19,7 +20,6 @@ In this walkthrough, we will need to edit the **root index**, which is the first
       ┗ 📜index.rst    ← this is the root index
 
 
-
 Explore the Root Index
 ----------------------
 If you open up :code:`sphinx-documentation-demo/index.rst`, you will notice a :code:`tocree` containing the following:
@@ -48,8 +48,8 @@ It's good idea to keep the contents of each tab in a separate directory in :code
 |
 
 
-Index File Layout for Tabs
---------------------------
+File Layout for Tabs
+====================
 The following is a quick sketch of where Sphinx would expect files to be based on the :code:`toctree` in :code:`docs/index.rst`:
 
 .. code-block::
@@ -91,14 +91,14 @@ It will be called "test_tab" and will be next to the other tabs already in our d
         test_tab/index
 
 Creating a "test document"
---------------------------
+==========================
 To make our new "test_tab" meaningful, we need to also add a document that can be viewed while within that tab.
 We will do this now:
 
 1. Create an empty "test" doc at :code:`docs/test_tab/test_doc.rst`
 2. Add the following text to the "test_doc" document:
 
-.. code-block::
+.. code-block:: txt
 
     Test Document
     =============
@@ -140,7 +140,7 @@ So when we added :code:`test_doc` to the previous toctree, it's assuming that th
         ┗ 📜test_doc.rst
 
 Build docs and explore the "test_tab"
-------------------------------------------
+==========================================
 Make sure to build your documentation using :code:`sphinx-build` or :code:`sphinx-autobuild`.
 
 .. figure:: images/guide_add_tab_final.png

diff --git a/docs/index.rst b/docs/index.rst
@@ -8,6 +8,8 @@ This is the root directory.
    guides/index
    tab_2/index
    tab_3/index
+
+..
    test_tab/index
 
 

diff --git a/docs/tab_2/index.rst b/docs/tab_2/index.rst
@@ -19,6 +19,4 @@ The caption for each toctree determines the section name.
 
    subject_3
    subject_4
-   subsection_2/index
-
-
+   subsection_2/index
diff --git a/docs/tab_2/subject_1.rst b/docs/tab_2/subject_1.rst
@@ -4,26 +4,23 @@ Subject_1
 This is a long page to test out some of the features of Sphinx.
 
 
-Section 1
+Heading
 =========
 
-Subsection 1
+Subheading
 ------------
 
-Sub-Subsection 1
+Sub-Subheading
 ~~~~~~~~~~~~~~~~
 
-Sub-Subsection 2
+Sub-Subheading
 ~~~~~~~~~~~~~~~~
 
-Sub-Subsection 3
-~~~~~~~~~~~~~~~~
-
-Subsection 2
+Subheading
 ------------
 
-Section 2
+Heading 2
 ============
 
-Subsection 3
+Subheading 2
 ------------