Insufficient documentation on how to build Rockcraft's documentation
Metadata
Current evaluation
Rockcraft now documents fresh-environment documentation setup, builds, linting and PR submission, and tests the guide; the obsolete docs/installdocs workflow has been replaced.
Suggested action: close resolved
Reason: The equivalent request in rockcraft#123 was completed by merged PR #126 in commit 68a7abda. The current tree includes build-docs.rst and an executable clean-tree test using make setup-docs and make docs; CONTRIBUTING.md also covers linting and opening a PR, and docs/Makefile no longer provides installdocs.
Evaluated by: mr-cal-bot
Impact:
35
Quick Win:
26
Complexity:
20
Confidence:
98
Actionability:
92
Issue body
### Request type
Fix
### What needs to get done
It's currently not possible to build Rockcraft's docs website [as described here](https://documentation.ubuntu.com/rockcraft/en/latest/tutorials/node-app/). The reason is, the article makes assumptions that a contributor understands how to get the environment setup.
Here's what one would get when running `make installdocs` from the `docs` folder:
```
$ make installdocs
. env/bin/activate; sphinx-build -M installdocs "." "_build" -q
/bin/sh: 1: .: cannot open env/bin/activate: No such file
make: *** [Makefile:49: installdocs] Error 2
```
Would be nice to have clear instructions on how to build the docs in a fresh environment. For example:
- Repo to clone
- Any particular branch to use?
- Which tools are required to build successfully? What needs to be installed? How?
- Where should the `make installdocs` command be run from?
In time, why not add a section to this page detailing how to propose your changes in a PR?
Thanks!
### Documentation location
https://documentation.ubuntu.com/rockcraft/en/latest/how-to/documentation/build-docs/
### Additional information
_No response_
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha |
Impact:
35
Quick Win:
26
Complexity:
20
Confidence:
98
Actionability:
92
|
close resolved | Rockcraft now documents fresh-environment documentation setup, builds, linting and PR submission, and tests the guide; the obsolete docs/installdocs workflow has been replaced. | |
| qwen/qwen3.6-35b-a3b |
Impact:
35
Quick Win:
18
Complexity:
20
Confidence:
60
Actionability:
65
|
keep open | Request for clearer documentation on building Rockcraft's docs locally. A contributor has expressed interest in working on it. | |
| qwen/qwen3.8-27b |
Impact:
30
Quick Win:
24
Staleness:
55
Complexity:
20
Confidence:
70
Support Request:
10
|
keep open | Docs gap: building Rockcraft's docs locally wasn't documented (make installdocs failed on fresh env). The build-docs how-to page now documents the current setup-docs/docs workflow, so the core request appears addressed; a contributor recently asked to be assigned. | |
| qwen/qwen3.6-35b-a3b |
Staleness:
65
Complexity:
20
Confidence:
85
Support Request:
30
|
needs triage | Unlabeled documentation request asking for clear instructions to build Rockcraft docs locally. Currently fails due to missing virtual environment setup. Awaiting maintainer review and assignment. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
80
Complexity:
10
Confidence:
85
Support Request:
10
|
needs triage | Contributor requests clearer local documentation build instructions, noting missing virtualenv setup steps. The issue remains open with no maintainer labels or responses, and an external contributor recently volunteered to address it. | |
| qwen3.6-35b-a3b-mtp-q6 |
Staleness:
70
Complexity:
15
Confidence:
85
Support Request:
10
|
needs triage | External contributor requests clearer instructions for building Rockcraft documentation locally. Issue lacks labels and maintainer response, with a recent comment from another contributor asking to be assigned. |
Update history
No update history recorded yet.
Related work
-
Duplicate Of:
rockcraft#123
(confidence 99%)
Same documentation-building how-to request, resolved by commit 68a7abda.
-
Related To:
rockcraft#1197
(confidence 90%)
Later clarification PR was closed unmerged to defer the change until the standard documentation contribution model.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #123 add how-to guide for "building docs" | rockcraft | closed | Added a guide for building Rockcraft documentation locally in PR canonical/rockcraft#126, merged as commit 68a7abda. | |
| #1197 docs: clarify how to build the documentation | rockcraft | closed | Closed unmerged; documentation-build clarifications were deferred until Rockcraft adopts its standard documentation contribution model. | |
| #584 Wrong Rockcraft version in readthedocs docs | rockcraft | closed | Fixed by merged PR #586: Read the Docs now fetches tags and labels unreleased documentation as dev instead of showing an outdated patch version. | |
| #2958 fix: update rockcraft documentation link to new url | charmcraft | merged | Merged PR #2958 updating legacy rockcraft documentation links from documentation.ubuntu.com to ubuntu.com/containers/rockcraft/docs across 10 files. | |
| #318 docs: automate CLI reference documentation | rockcraft | merged | Merged PR #318 in commit ca1b1c20, automating Rockcraft's CLI reference documentation and implementing CRAFT-1779. | |
| #101 docs for `rockcraft clean` | rockcraft | closed | Documentation for `rockcraft clean` was requested after #93 added the command in c4502a7a, but no resolving docs PR or commit was identified before closure. | |
| #800 docs: add remote-build how-to | rockcraft | merged | Merged docs PR canonical/rockcraft#800 (commit a07a6e6a) adding a remote-build how-to guide, +152 lines across 3 docs files, documenting the experimental `rockcraft remote-build` command. |