From 8faa6d54eef1f4437c7e10337ed8fdcc8dc51cbc Mon Sep 17 00:00:00 2001
From: Michael DuBelko <michael.dubelko@canonical.com>
Date: Fri, 13 Sep 2024 09:19:17 -0700
Subject: [PATCH] docs: document tox builds (#5033)

- Remove snapcraft_legacy as an autobuild target, since it was blocking.
- Add temporary documentation to HACKING.md, since it likely won't
remain after we impose README standards.

Co-authored-by: Alex Lowe <alex.lowe@canonical.com>
---
 HACKING.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 tox.ini    |  2 +-
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/HACKING.md b/HACKING.md
index 44622ea88d..31d93e2f35 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -54,6 +54,48 @@ See the [Testing guide](TESTING.md).
 
 Given that the `--debug` option in snapcraft is reserved for project specific debugging, enabling for the `logger.debug` calls is achieved by setting the "SNAPCRAFT_ENABLE_DEVELOPER_DEBUG" environment variable to a truthful value. Snapcraft's internal tools, e.g.; `snapcraftctl` should pick up this environment variable as well.
 
+
+## Documentation
+
+
+### Build
+
+To render the documentation as HTML in `docs/_build`, run:
+
+```shell
+tox run -e build-docs
+```
+
+> **Important**
+> 
+> Interactive builds are currently defective and cause an infinite loop. [This GitHub issue](https://github.com/sphinx-doc/sphinx/issues/11556#issuecomment-1667451983) posits that this is caused by by pages referencing each other.
+
+If you prefer to compose pages interactively, you can host the documentation on a local server:
+
+```shell
+tox run -e autobuild-docs
+```
+
+You can reach the interactive site at http://127.0.0.1:8080 in a web browser.
+
+
+### Test
+
+The documentation Makefile provided by the [Sphinx Starter Pack](https://github.com/canonical/sphinx-docs-starter-pack) provides a number of natural language checks such as style guide adherence, inclusive words, and product terminology, however they currently aren't configured correctly for Snapcraft. Instead, you can validate for basic language and syntax using two of the development tests.
+
+To check for syntax errors in documentation, run:
+
+```shell
+tox run -e lint-docs
+```
+
+For a rudimentary spell check, you can use codespell:
+
+```shell
+tox run -e lint-codespell
+```
+
+
 ## Evaluating pull requests
 
 Oftentimes all you want to do is see if a given pull request solves the issue you were having. To make this easier, the Travis CI setup for snapcraft _publishes_ the resulting snap that was built for x86-64 using `transfer.sh`.
diff --git a/tox.ini b/tox.ini
index 0d9b1d7f1d..0f1e5187b0 100644
--- a/tox.ini
+++ b/tox.ini
@@ -169,7 +169,7 @@ commands = sphinx-build {posargs:-b html} -W {tox_root}/docs {tox_root}/docs/_bu
 [testenv:autobuild-docs]
 description = Build documentation with an autoupdating server
 base = docs
-commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} -W --watch {tox_root}/snapcraft {tox_root}/snapcraft_legacy {tox_root}/docs {tox_root}/docs/_build
+commands = sphinx-autobuild {posargs:-b html --open-browser --port 8080} {tox_root}/docs {tox_root}/docs/_build
 
 [testenv:lint-docs]
 description = Lint the documentation with sphinx-lint