Workflow for documentation contributors needs to be improved

Metadata

Project: charmcraft
Number: #2180
Type: issue
State: open
Author: evildmp
Labels: —
Created: 2025-02-19 09:15 PM UTC
Updated: 2025-08-15 03:17 PM UTC
Closed: —

Current evaluation

Request to standardize Sphinx docs build workflow to 'cd docs && make install && make run'. The current docs/Makefile already has both 'install' and 'run' targets matching this exact workflow, introduced by the canonical starter pack 1.5 update in PR #2594. Issue is unlabelled with zero comments and no activity in over a year.

Suggested action: close stale

Reason: The requested workflow is already implemented: docs/Makefile defines 'install: $(DOCS_VENVDIR)' and 'run: install' (sphinx-autobuild), matching the issue's exact ask. These targets were introduced by commit 6264ff78 'build(docs)!: update canonical starter pack to 1.5 (#2594)', which postdates this issue (#2180). The issue has had zero comments, no labels, and no activity for 381+ days, and the underlying problem is no longer applicable.

Impact: 30 Quick Win: 24.0 Staleness: 80 Complexity: 20 Confidence: 72 Support Request: 10

Issue body

### What needs to get done All Canonical documentation that uses Sphinx should adhere to the same workflow model. It should be possible to build the documentation with: ``` cd docs make install make run ``` If there is a reason why this isn't possible, it needs to be a very good one. I would like to see this workflow implemenedt here. ### Why it needs to get done Every step that a documentation contributor has to make before they can build the documentation locally is a barrier. Documentation that includes any barrier that is not absolutely necessary undermines the entire premise of the agreement for using Sphinx for documentation.

Evaluation history

Date	Model	Scores	Action	Summary
2026-09-01 12:09 AM UTC	qwen/qwen3.8-27b	Impact: 30 Quick Win: 24.0 Staleness: 80 Complexity: 20 Confidence: 72 Support Request: 10	close stale	Request to standardize Sphinx docs build workflow to 'cd docs && make install && make run'. The current docs/Makefile already has both 'install' and 'run' targets matching this exact workflow, introduced by the canonical starter pack 1.5 update in PR #2594. Issue is unlabelled with zero comments and no activity in over a year.
2026-07-22 12:29 AM UTC	qwen/qwen3.6-35b-a3b	Staleness: 95 Complexity: 40 Confidence: 80 Support Request: 10	needs triage	Request to standardize Sphinx documentation build workflow to make install and make run to reduce contributor barriers. Unlabelled, zero comments, and inactive for over a year.
2026-07-07 08:14 PM UTC	qwen3.6-35b-a3b-mtp-q6	Staleness: 85 Complexity: 40 Confidence: 90 Support Request: 10	needs triage	Request to standardize and simplify the local documentation build workflow to reduce contributor barriers. Currently unlabelled and inactive for over a year.
2026-07-05 02:11 AM UTC	qwen3.6-35b-a3b-mtp-q6	Staleness: 90 Complexity: 20 Confidence: 75 Support Request: 15	needs triage	Request to standardize Sphinx documentation build workflow to reduce contributor barriers. Untriaged, inactive for over a year with no maintainer response or labels.
2026-06-15 09:20 PM UTC	qwen3.6-35b-a3b-mtp-q6	Staleness: 80 Complexity: 20 Confidence: 90 Support Request: 10	needs triage	Standardize Sphinx documentation build workflow to make install and make run to reduce contributor friction. Open, unassigned, and inactive for over 300 days with no comments or labels, requiring triage.

Update history

No update history recorded yet.

Related work

Likely Fixed By: canonical/charmcraft#2594 (confidence 75%)
Commit 6264ff78 'build(docs)!: update canonical starter pack to 1.5' introduced the current docs/Makefile with 'install' and 'run' targets that match the workflow requested in this issue. PR number 2594 > issue number 2180, confirming it postdates the issue.

Related issues

No related issues found above the similarity threshold.