Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: document tox builds #5033

Merged
merged 4 commits into from
Sep 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions HACKING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion tox.ini
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading