Skip to content

Commit f5ab07f

Browse files
committed
Update install guide
1 parent 60b92fe commit f5ab07f

File tree

1 file changed

+45
-1
lines changed

1 file changed

+45
-1
lines changed

docs/guides/guide_installation.rst

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,10 +129,54 @@ While there already a page set up for the :code`sphinx-documentation-demo` proje
129129
2. Using GitHub Workflow to Build Documentation
130130
-----------------------------------------------
131131
GitHub can automatically discover workflows located in the :code:`.github/workflows` directory within the project directory.
132-
We will be using a workflow to build documentation whenever a new commit is pushed to the repository.
132+
We will be using a workflow to build documentation whenever a **new commit is pushed to the repository**.
133133

134134
2a. Example Workflow
135135
~~~~~~~~~~~~~~~~~~~~
136136
We will be reviewing the workflow that :code:`sphinx-documentation-demo` uses.
137+
137138
You can find the workflow in :code:`sphinx-documentation-demo/.github/workflows/documentation.yml`
138139

140+
.. code-block:: yml
141+
:emphasize-lines: 16,19,24,26
142+
:linenos:
143+
144+
name: documentation
145+
146+
on: [push, pull_request, workflow_dispatch]
147+
148+
permissions:
149+
contents: write
150+
151+
jobs:
152+
docs:
153+
runs-on: ubuntu-latest
154+
steps:
155+
- uses: actions/checkout@v3
156+
- uses: actions/setup-python@v3
157+
- name: Install dependencies
158+
run: |
159+
pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
160+
- name: Sphinx build
161+
run: |
162+
sphinx-build docs _build
163+
- name: Deploy to GitHub Pages
164+
uses: peaceiris/actions-gh-pages@v3
165+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
166+
with:
167+
publish_branch: gh-pages
168+
github_token: ${{ secrets.GITHUB_TOKEN }}
169+
publish_dir: _build/
170+
force_orphan: true
171+
172+
173+
* **Line 16.** Install dependencies
174+
* This tells GitHub to install sphinx and its dependencies to the ubuntu image.
175+
* **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.
176+
* **Line 19.** Build Docs
177+
* This runs :code:`sphinx-build` on the :code:`docs/` directory (in the repo) and creates the :code:`_build/` directory.
178+
* Line 24. Publish to branch
179+
* After building the docs, this line tells GitHub to publish the changes to the :code:`gh-pages` branch.
180+
* **Note**: this needs to be the same branch that GitHub Pages is set to publish with.
181+
* **Line 26.** Specify directory to publish
182+
* This informs GitHub Pages where the static HTML documentation (built by :code:`sphinx-build`) is located.

0 commit comments

Comments
 (0)