move few GH-unrelated points to earlier episode

part of #282
coderefinery · Sep 23, 2023 · 4efe6c5 · 4efe6c5
1 parent bc2335d
commit 4efe6c5
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 18 deletions.
diff --git a/content/gh_workflow.md b/content/gh_workflow.md
@@ -56,14 +56,6 @@ Inside the cloned repository, build the documentation and verify the result in y
 $ sphinx-build doc _build
 ```
 
-**Test HTML pages links**
-
-Inside the cloned repository, check the integrity of all internal and external links:
-
-```console
-$ sphinx-build doc -W -b linkcheck -d _build/doctrees _build/html
-```
-
 **Step 2:** Add the GitHub Action
 
 - Create a new file at `.github/workflows/documentation.yaml` with the contents
@@ -126,15 +118,6 @@ Finally, make some changes to your documentation
 - Commit and push them, and verify that the documentation website refreshes after your changes (can take few seconds or a minute)
 ``````
 
-```{callout} Do not add the generated build directory to your repository
-The `_build` directory is generated locally with the command `sphinx-build
-doc _build` and allows you to check the content locally but it should not be
-part of the Git repository.  We recommend to add `_build` to `.gitignore` to
-prevent you from accidentally adding files below `_build` to the Git
-repository.
-```
-
-
 ## Alternatives to GitHub Pages
 
 - [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/)

diff --git a/content/sphinx.md b/content/sphinx.md
@@ -377,11 +377,23 @@ extensions = ['myst_parser', "sphinx.ext.autodoc"]
 `````
 
 
-## References and next steps
+## Good to know
 
+- The `_build` directory is a generated directory
+  and should not be part of the Git repository.  We recommend to add `_build`
+  to `.gitignore` to prevent you from accidentally adding files below
+  `_build` to the Git repository.
 - [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/)
   provides a local web server that will automatically refresh your view
   every time you save a file - which makes writing and testing much easier.
+- This is useful if you want to check the integrity of all internal and external links:
+  ```console
+  $ sphinx-build . -W -b linkcheck _build
+  ```
+
+
+## References
+
 - [Sphinx documentation](https://www.sphinx-doc.org/)
 - [Sphinx + ReadTheDocs guide](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/index.html)
 - For more Markdown functionality, see the [Markdown guide](https://www.markdownguide.org/basic-syntax/).