Skip to content

docs: add how-to guide for sphinx autodocs extension#450

Merged
AshleyCliff merged 10 commits into
canonical:mainfrom
AshleyCliff:autodocs
Oct 16, 2025
Merged

docs: add how-to guide for sphinx autodocs extension#450
AshleyCliff merged 10 commits into
canonical:mainfrom
AshleyCliff:autodocs

Conversation

@AshleyCliff

@AshleyCliff AshleyCliff commented Oct 13, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor
  • Have you updated CHANGELOG.md with relevant non-documentation file changes?
  • Have you updated the documentation for this change?

Adds a minimal how-to to set up the sphinx autodocs extensions and use it with the starter pack.

@AshleyCliff AshleyCliff self-assigned this Oct 13, 2025
@AshleyCliff AshleyCliff marked this pull request as ready for review October 13, 2025 18:59
@AshleyCliff AshleyCliff added documentation Improvements or additions to documentation enhancement New feature or request labels Oct 13, 2025
akcano
akcano requested changes Oct 14, 2025
View reviewed changes
Comment thread docs/how-to/autodocs.md Outdated
Comment thread docs/how-to/import-docstrings-with-autodoc.md Outdated
Comment thread docs/how-to/autodocs.md Outdated
Comment thread docs/how-to/autodocs.md Outdated
Comment thread docs/how-to/import-docstrings-with-autodoc.md
Comment thread docs/how-to/index.rst Outdated
@AshleyCliff AshleyCliff requested a review from akcano October 14, 2025 15:51
akcano
akcano approved these changes Oct 14, 2025
View reviewed changes

@akcano akcano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, one minor nitpick.

Comment thread docs/how-to/autodoc.md Outdated
minaelee
minaelee suggested changes Oct 15, 2025
View reviewed changes

@minaelee minaelee left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few nits. Thanks for this!

Comment thread docs/how-to/autodoc.md Outdated
Comment thread docs/how-to/autodoc.md Outdated
Comment thread docs/how-to/autodoc.md Outdated
Comment thread docs/how-to/import-docstrings-with-autodoc.md Outdated

## Prerequisites

To use the Sphinx autodoc extension with the Starter Pack, you need:

@minaelee minaelee Oct 15, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To use the Sphinx autodoc extension with the Starter Pack, you need:
To use the Sphinx `autodoc` extension with the Starter Pack, you need:

@minaelee minaelee Oct 16, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this change wasn't accepted while the same change in other places was? It's a super small nit but just for consistency.

Comment thread docs/how-to/autodoc.md Outdated
Comment thread docs/how-to/import-docstrings-with-autodoc.md Outdated
AnneCYH
AnneCYH reviewed Oct 15, 2025
View reviewed changes
Comment thread docs/how-to/autodoc.md Outdated
Comment thread docs/how-to/import-docstrings-with-autodoc.md
Comment thread docs/how-to/autodoc.md Outdated
AnneCYH
AnneCYH requested changes Oct 15, 2025
View reviewed changes

@AnneCYH AnneCYH left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this @AshleyCliff !

I think the CHANGELOG could do with a short addition about 'introducing autodocs support in the starter pack', something along those lines.

Thanks!

@AshleyCliff

AshleyCliff commented Oct 15, 2025 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Regarding the CHANGELOG - the checkbox for the PR says 'relevant non-documentation file changes', since this is only documentation should I add something or not?

@AshleyCliff AshleyCliff requested a review from minaelee October 15, 2025 13:38
@AnneCYH

AnneCYH commented Oct 15, 2025

Copy link
Copy Markdown
Contributor

Hi @AshleyCliff !

https://github.com/canonical/sphinx-docs-starter-pack/blob/main/CHANGELOG.md?plain=1#L6

This line was added by @medubelko for my PR; no other documentation-related changes were added. Maybe he can help to clarify a bit more on the CHANGELOG requirements.

@AshleyCliff
docs: update changelog for autodoc
c050244 
Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>
minaelee
minaelee suggested changes Oct 16, 2025
View reviewed changes

@minaelee minaelee left a comment •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One typo fix needed!

minaelee
minaelee suggested changes Oct 16, 2025
View reviewed changes
Comment thread docs/how-to/import-docstrings-with-autodoc.md Outdated
@AshleyCliff
fix: autodoc spell fix
e280904 
Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>
@AshleyCliff AshleyCliff requested a review from minaelee October 16, 2025 19:53
minaelee
minaelee suggested changes Oct 16, 2025
View reviewed changes
Comment thread docs/how-to/import-docstrings-with-autodoc.md Outdated

## Prerequisites

To use the Sphinx autodoc extension with the Starter Pack, you need:

@minaelee minaelee Oct 16, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this change wasn't accepted while the same change in other places was? It's a super small nit but just for consistency.

@AshleyCliff
fix: autodoc formatting
c006f42 
Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>
minaelee
minaelee approved these changes Oct 16, 2025
View reviewed changes

@minaelee minaelee left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm, thanks for adding this!

@AshleyCliff AshleyCliff merged commit fc52ee9 into canonical:main Oct 16, 2025
7 checks passed
SecondSkoll added a commit that referenced this pull request Nov 13, 2025
@SecondSkoll @waveform80
@dwilding @erinecon @rkratky @medubelko @tarek-y-ismail @lengau @k-dimple @AnneCYH @akcano @jahn-junior @AshleyCliff @msuchane @MggMuggins @network-charles
feat: Update stable branch with 1.3.0 release (#465)
e2d12d7 
* fix: CLA check to run on PRs only

* refactor: Replace build_metrics.sh with something nicer (#373)

* Replace build_metrics.sh with something nicer

* docs: update changelog

* docs: fix info about setting RTD key as GitHub deploy key (#423)

* fix: spelling mistake in update script (#425)

* fix spelling mistake in update script

* add change to CHANGELOG.md

* Add warning to set-up-automated-testing.rst (#427)

* feat: exclude generated pages from sitemap by default, document wildcards (#429)

* add info about wildcard excludes

* add placeholder sitemap_excludes in conf.py

* adjust wording of comment

* enable typical sitemap_excludes by default

* use consistent wording and formatting

* Use long parameter for 'fail on warning' (#430)

* docs: add troubleshooting how-to (#432)

Add tag desync as the first issue.

* Fix stale references to `custom_conf.py` (#433)

* fix(ci): make check-removed-urls work with private forks (#437)

* fix(ci): make check-removed-urls work with private forks

Fixes #436

* docs: update changelog

* chore: add `CODEOWNERS` (#439)

* chore: add `CODEOWNERS`

Enumerate individual reviewers for now.

Later, we can add a Sphinx development team, once we've established one.

* docs: add #438 to changelog

* chore: missing hyphen

Co-authored-by: Michael Park <michael.park@canonical.com>

* chore: revert changelog entry

Co-authored-by: Michael Park <michael.park@canonical.com>

---------

Co-authored-by: Michael Park <michael.park@canonical.com>

* Update Open Graph image URL in conf.py (#441)

The preview image being used was an old one, and the design team has suggested the use of this one instead.

* Update workflow action versions (#445)

* update workflow action versions

* update changelog

* Update CHANGELOG.md

Co-authored-by: Dave Wilding <david.wilding@canonical.com>

---------

Co-authored-by: Dave Wilding <david.wilding@canonical.com>

* Fix whitespace and executable flag of scripts (#448)

* make scripts executable

* remove whitespace from vale script

* update CHANGELOG.md

* docs: add how-to guide for Mermaid diagramming tool (#442)

Signed-off-by: annecyh <anne.chew@canonical.com>

* Move from canonical-sphinx-exensions to individual packages (#449)

* Move from canonical-sphinx-exensions to individual packages

* Update CHANGELOG.md

* build(deps): bump sphinx-terminal to v0.1.1 (#454)

* docs: add how-to guide for sphinx autodoc extension (#450)

* docs: update how to index.rst add autodocs

* docs: create autodocs.md

* fix: conf file formatting in autodocs.md

* fix: fix conf.py formatting in autodocs.md

* fix: pr comment updates

* fix: requested pr changes

Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>

* fix: autodoc table formatting

Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>

* docs: update changelog for autodoc

Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>

* fix: autodoc spell fix

Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>

* fix: autodoc formatting

Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>

---------

Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>

* build: move Vale dependencies to requirements.txt (#456)

* move Vale dependencies to requirements.txt

* add PR link to CHANGELOG.md

* Add OpenAPI how-to guide (#446)

* Add OpenAPI how-to guide

* Include RTD steps in OpenAPI how-to guide

* docs: add guidelines for using custom base templates (#455)

* docs: add guidelines for using custom base templates

Signed-off-by: annecyh <anne.chew@canonical.com>

* docs: add a how-to guide for data tables (#451)

* add first draft of data tables guide

* add data tables guide to index

* add details about Sphinx DataTables

* adjust wording

* update landing page per suggestion

* adjust wording

* mention new doc in CHANGELOG

* remove full stop

* put links in alphabetical order

* use reST formatting

* explain purpose of links and remove duplicated links

* improve wording per review

* docs: consolidate custom template information (#459)

Signed-off-by: annecyh <anne.chew@canonical.com>

* Details about sphinx-terminal (#447)

* Details about sphinx-terminal

* Describe the terminal copy button

Co-authored-by: JJ Coldiron <jj.coldiron@canonical.com>

* fix(build): remove em dash from fallback target (#461)

 #388 introduced an emdash in the makefile that was almost certainly not
intended; this causes the fallthrough case to infinitely recurse.

---------

Signed-off-by: Wesley Hershberger <wesley.hershberger@gmail.com>
Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com>

* feat!: incorporate redesigned terminal (#460)

* fix(docs): update style guide redirects (#453)

* docs: add step to remove CODEOWNERS in the tutorial (#458)

Reorganise the first two sections so copying and pruning files are
discrete actions.

* Ensure update_sp.py is executable from any directory not just docs/ (#424)

* ensure this file is executable from any directory not just docs/

* Add a new line

* update requirements.txt path

* update NEWFILES.txt path

* chore: refactor makefile (#426)

Co-authored-by: Michael Park <michael.park@canonical.com>

* chore: Remove `ALLFILES` from makefile (#434)

* Remove `ALLFILES` from Makefile

* Update changelog

---------

Co-authored-by: Michael Park <michael.park@canonical.com>

* feat: better canonical URL support (#462)

* fix: config for canonical URL

* docs: update html_baseurl context in conf file

* Update CHANGELOG.md

* Update CHANGELOG.md

* chore: reword changelog entry

* chore: bump version

* fix: CHANGELOG

* fix: spelling issues

---------

Signed-off-by: annecyh <anne.chew@canonical.com>
Signed-off-by: Ashley Cliff <ashley.cliff@canonical.com>
Signed-off-by: Wesley Hershberger <wesley.hershberger@gmail.com>
Co-authored-by: Dave Jones <dave@waveform.org.uk>
Co-authored-by: Dave Wilding <david.wilding@canonical.com>
Co-authored-by: Erin Conley <erin.conley@canonical.com>
Co-authored-by: Robert Krátký <robert.kratky@canonical.com>
Co-authored-by: Michael DuBelko <michael.dubelko@canonical.com>
Co-authored-by: tarek-y-ismail <tarek.ismail@canonical.com>
Co-authored-by: Alex Lowe <alex.lowe@canonical.com>
Co-authored-by: Dimple Kuriakose <123362247+k-dimple@users.noreply.github.com>
Co-authored-by: AnneCYH <anne.chew@canonical.com>
Co-authored-by: Artem Konev <141050460+akcano@users.noreply.github.com>
Co-authored-by: JJ Coldiron <jj.coldiron@canonical.com>
Co-authored-by: Ashley Cliff <ashley.cliff@canonical.com>
Co-authored-by: Marek Suchánek <marek.suchanek@canonical.com>
Co-authored-by: Wesley Hershberger <wesley.hershberger@canonical.com>
Co-authored-by: Michael DuBelko <michael.dubelko@gmail.com>
Co-authored-by: Charles Uneze <charlesniklaus@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AnneCYH AnneCYH AnneCYH approved these changes
@akcano akcano akcano approved these changes
@dwilding dwilding Awaiting requested review from dwilding dwilding is a code owner
@medubelko medubelko Awaiting requested review from medubelko medubelko is a code owner
@rkratky rkratky Awaiting requested review from rkratky rkratky is a code owner
@SecondSkoll SecondSkoll Awaiting requested review from SecondSkoll SecondSkoll is a code owner
@tang-mm tang-mm Awaiting requested review from tang-mm tang-mm is a code owner
+1 more reviewer
@minaelee minaelee minaelee approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

@AshleyCliff AshleyCliff

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@AshleyCliff @AnneCYH @minaelee @akcano