Skip to content

Commit 98b50a9

Browse files
jramsdell-btjramsdell-bt
committed
Update docs
1 parent ddb1b1b commit 98b50a9

File tree

4 files changed

+131
-128
lines changed

4 files changed

+131
-128
lines changed

‎docs/guides/guide_installation.rst

+6-126
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,11 @@
11
Installing Sphinx
22
=================
3+
This guide will cover how to install Sphinx **locally** on your laptop.
4+
When you need to write a lot of documentation, it's a **good idea** to do it all locally.
5+
We will go over:
36

4-
5-
Local Installation
6-
==================
7-
8-
.. tip::
9-
When you need to write a lot of documentation, it's a **good idea to do it all locally.**
7+
1. Installing Sphinx using a virtual environment
8+
2. How to build documentation locally using Sphinx
109

1110

1211
1. Cloning the Repo
@@ -87,123 +86,4 @@ While in the virtual environment, run the following command:
8786
8887
sphinx-autobuild docs _build
8988
90-
You can then point your web browser to: http://127.0.0.1:8000/
91-
92-
Remote Build on GitHub
93-
======================
94-
The :code:`_build` directory **should not be pushed to GitHub**.
95-
Instead we will use a GitHub Workflow to automatically build documentation that is pushed to the repository.
96-
The built documentation will then be automatically served up on a webpage in :code:`GitHub Pages`
97-
98-
1. Set up GitHub Pages
99-
----------------------
100-
GitHub Pages allow users to view web pages generated by our documentation.
101-
While there already a page set up for the :code`sphinx-documentation-demo` project, you will need to do the following steps for a new project:
102-
103-
1a. Navigate to Page settings
104-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105-
.. figure:: images/guide_install_repo_settings.png
106-
:class: sd-border-2
107-
108-
Click the Settings tab in the project you want to add to GitHub Pages.
109-
110-
111-
.. figure:: images/guide_install_repo_page_tab.png
112-
:class: sd-border-2
113-
114-
Click the Pages tab (in the left sidebar) in the Settings page.
115-
116-
117-
1b. Select branch to use with GitHub Pages
118-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119-
.. warning::
120-
121-
The GitHub repo must be **public** in order for it to be accessible via GitHub Pages.
122-
123-
.. figure:: images/guide_install_page_branch.png
124-
:class: sd-border-2
125-
126-
When documentation is successfully deployed, you will see a link that looks like :code:`A`. For a new repo, this will not be active.
127-
You will need to set the branch (see :code:`B`).
128-
This demo uses a separate branch called :code:`gh-pages` to deploy documentation.
129-
130-
2. Using GitHub Workflow to Build Documentation
131-
-----------------------------------------------
132-
GitHub can automatically discover workflows located in the :code:`.github/workflows` directory within the project directory.
133-
We will be using a workflow to build documentation whenever a **new commit is pushed to the repository**.
134-
135-
2a. Example Workflow
136-
~~~~~~~~~~~~~~~~~~~~
137-
We will be reviewing the workflow that :code:`sphinx-documentation-demo` uses.
138-
139-
You can find the workflow in :code:`sphinx-documentation-demo/.github/workflows/documentation.yml`
140-
141-
.. code-block::
142-
:emphasize-lines: 16,19,24,26
143-
:linenos:
144-
145-
name: documentation
146-
147-
on: [push, pull_request, workflow_dispatch]
148-
149-
permissions:
150-
contents: write
151-
152-
jobs:
153-
docs:
154-
runs-on: ubuntu-latest
155-
steps:
156-
- uses: actions/checkout@v3
157-
- uses: actions/setup-python@v3
158-
- name: Install dependencies
159-
run: |
160-
pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
161-
- name: Sphinx build
162-
run: |
163-
sphinx-build docs _build
164-
- name: Deploy to GitHub Pages
165-
uses: peaceiris/actions-gh-pages@v3
166-
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
167-
with:
168-
publish_branch: gh-pages
169-
github_token: ${{ secrets.GITHUB_TOKEN }}
170-
publish_dir: _build/
171-
force_orphan: true
172-
173-
174-
* **Line 16.** Install dependencies
175-
* This tells GitHub to install sphinx and its dependencies to the ubuntu image.
176-
* **Note**: After you add a new sphinx extension to :code:`pyproject.toml` and to :code:`docs/conf.py`, you'll also need to add the dependency to the list on line 16.
177-
* **Line 19.** Build Docs
178-
* This runs :code:`sphinx-build` on the :code:`docs/` directory (in the repo) and creates the :code:`_build/` directory.
179-
* Line 24. Publish to branch
180-
* After building the docs, this line tells GitHub to publish the changes to the :code:`gh-pages` branch.
181-
* **Note**: this needs to be the same branch that GitHub Pages is set to publish with.
182-
* **Line 26.** Specify directory to publish
183-
* This informs GitHub Pages where the static HTML documentation (built by :code:`sphinx-build`) is located.
184-
185-
186-
3. Verifying GitHub Workflow Actions
187-
------------------------------------
188-
Using the previously mentioned workflow, a GitHub Action will be triggered whenever a commit is pushed to the repo.
189-
You can monitor running jobs from your GitHub Repository.
190-
191-
.. figure:: images/guide_install_github_actions_tab.png
192-
:class: sd-border-2
193-
194-
Click on the :code:`Actions` tab.
195-
196-
.. figure:: images/guide_install_actions_build.png
197-
:class: sd-border-2
198-
199-
Current and previous workflow runs are listed in the Actions tab.
200-
The color of the icon indicates the current status of the run.
201-
You may notice a :code:`pages build and deployment` job running. This is reponsible for building the docs.
202-
203-
.. figure:: images/guide_install_actions_error.png
204-
:class: sd-border-2
205-
206-
A red icon indicates that the run has failed. You can click on a run to get debug info for each step.
207-
Featured in this figure is a very common error: sphinx is missing an extension because it was not installed in the :code:`documentation.yml` workflow.
208-
209-
To fix this, :code:`sphinx-copybutton` had to be added to line 16 in :code:`documentation.yml` (see :ref:`2a. Example Workflow`)
89+
You can then point your web browser to: http://127.0.0.1:8000/

‎docs/guides/guide_remote.rst

+122
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
Hosting Sphinx on GitHub Pages
2+
==============================
3+
4+
While you can install Sphinx on your laptop and build documentation locally, ultimately you will want to share docs via a web server.
5+
To do this, we will go over:
6+
7+
8+
1. Setting up GitHub pages for a repository
9+
2. Using GitHub Workflows to automate building documentation
10+
11+
1. Set up GitHub Pages
12+
======================
13+
GitHub Pages allow users to view web pages generated by our documentation.
14+
While there already a page set up for the :code:`sphinx-documentation-demo` project, you will need to do the following steps for a new project:
15+
16+
1a. Navigate to Page settings
17+
-----------------------------
18+
.. figure:: images/guide_install_repo_settings.png
19+
:class: sd-border-2
20+
21+
Click the Settings tab in the project you want to add to GitHub Pages.
22+
23+
24+
.. figure:: images/guide_install_repo_page_tab.png
25+
:class: sd-border-2
26+
27+
Click the Pages tab (in the left sidebar) in the Settings page.
28+
29+
30+
1b. Select branch to use with GitHub Pages
31+
------------------------------------------
32+
.. warning::
33+
34+
The GitHub repo must be **public** in order for it to be accessible via GitHub Pages.
35+
36+
.. figure:: images/guide_install_page_branch.png
37+
:class: sd-border-2
38+
39+
When documentation is successfully deployed, you will see a link that looks like :code:`A`. For a new repo, this will not be active.
40+
You will need to set the branch (see :code:`B`).
41+
This demo uses a separate branch called :code:`gh-pages` to deploy documentation.
42+
43+
2. Using GitHub Workflow to Build Documentation
44+
===============================================
45+
GitHub can automatically discover workflows located in the :code:`.github/workflows` directory within the project directory.
46+
We will be using a workflow to build documentation whenever a **new commit is pushed to the repository**.
47+
48+
2a. Example Workflow
49+
--------------------
50+
We will be reviewing the workflow that :code:`sphinx-documentation-demo` uses.
51+
52+
You can find the workflow in :code:`sphinx-documentation-demo/.github/workflows/documentation.yml`
53+
54+
.. code-block::
55+
:emphasize-lines: 16,19,24,26
56+
:linenos:
57+
58+
name: documentation
59+
60+
on: [push, pull_request, workflow_dispatch]
61+
62+
permissions:
63+
contents: write
64+
65+
jobs:
66+
docs:
67+
runs-on: ubuntu-latest
68+
steps:
69+
- uses: actions/checkout@v3
70+
- uses: actions/setup-python@v3
71+
- name: Install dependencies
72+
run: |
73+
pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
74+
- name: Sphinx build
75+
run: |
76+
sphinx-build docs _build
77+
- name: Deploy to GitHub Pages
78+
uses: peaceiris/actions-gh-pages@v3
79+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
80+
with:
81+
publish_branch: gh-pages
82+
github_token: ${{ secrets.GITHUB_TOKEN }}
83+
publish_dir: _build/
84+
force_orphan: true
85+
86+
87+
* **Line 16.** Install dependencies
88+
* This tells GitHub to install sphinx and its dependencies to the ubuntu image.
89+
* **Note**: After you add a new sphinx extension to :code:`pyproject.toml` and to :code:`docs/conf.py`, you'll also need to add the dependency to the list on line 16.
90+
* **Line 19.** Build Docs
91+
* This runs :code:`sphinx-build` on the :code:`docs/` directory (in the repo) and creates the :code:`_build/` directory.
92+
* Line 24. Publish to branch
93+
* After building the docs, this line tells GitHub to publish the changes to the :code:`gh-pages` branch.
94+
* **Note**: this needs to be the same branch that GitHub Pages is set to publish with.
95+
* **Line 26.** Specify directory to publish
96+
* This informs GitHub Pages where the static HTML documentation (built by :code:`sphinx-build`) is located.
97+
98+
99+
3. Verifying GitHub Workflow Actions
100+
====================================
101+
Using the previously mentioned workflow, a GitHub Action will be triggered whenever a commit is pushed to the repo.
102+
You can monitor running jobs from your GitHub Repository.
103+
104+
.. figure:: images/guide_install_github_actions_tab.png
105+
:class: sd-border-2
106+
107+
Click on the :code:`Actions` tab.
108+
109+
.. figure:: images/guide_install_actions_build.png
110+
:class: sd-border-2
111+
112+
Current and previous workflow runs are listed in the Actions tab.
113+
The color of the icon indicates the current status of the run.
114+
You may notice a :code:`pages build and deployment` job running. This is reponsible for building the docs.
115+
116+
.. figure:: images/guide_install_actions_error.png
117+
:class: sd-border-2
118+
119+
A red icon indicates that the run has failed. You can click on a run to get debug info for each step.
120+
Featured in this figure is a very common error: sphinx is missing an extension because it was not installed in the :code:`documentation.yml` workflow.
121+
122+
To fix this, :code:`sphinx-copybutton` had to be added to line 16 in :code:`documentation.yml` (see :ref:`2a. Example Workflow`)

‎docs/guides/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Guides
88

99
guide_what_is_sphinx
1010
guide_installation
11+
guide_remote
1112

1213
.. toctree::
1314
:maxdepth: 1

‎docs/guides/walkthrough_adding_new_tab.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ The following is a quick sketch of where Sphinx would expect files to be based o
6464
┃ ┗ 📜index.rst ← index for tab "tab_3"
6565
┗ 📜index.rst ← root index
6666
67-
Creating "test" tab folder and empty index
67+
Creating "test_tab" folder and empty index
6868
------------------------------------------
6969
We will now try to add a new tab to Sphinx.
7070
It will be called "test_tab" and will be next to the other tabs already in our documentation.
@@ -77,7 +77,7 @@ It will be called "test_tab" and will be next to the other tabs already in our d
7777

7878
1. Create a new empty directory called "test" at: :code:`docs/test_tab/`
7979
2. Create a new empty "index.rst" file at: :code:`docs/test_tab/index.rst`
80-
3. Inside :code:`docs/index.rst`, in the indented :code:`toctree`, append the line :code:`test_tab/index`. It should look like the following:
80+
3. Inside :code:`docs/index.rst`, in the indented :term:`toctree`, append the line :code:`test_tab/index`. It should look like the following:
8181

8282

8383
.. code-block::

0 commit comments

Comments
 (0)