Skip to content

docs: add guidelines for using custom base templates#455

Merged
AnneCYH merged 4 commits intomainfrom
annecyh/custom-base-templates
Oct 20, 2025
Merged

docs: add guidelines for using custom base templates#455
AnneCYH merged 4 commits intomainfrom
annecyh/custom-base-templates

Conversation

@AnneCYH
Copy link
Copy Markdown
Contributor

@AnneCYH AnneCYH commented Oct 16, 2025 •
edited
Loading

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

@AnneCYH
docs: add guidelines for using custom base templates
8289fe6 
Signed-off-by: annecyh <anne.chew@canonical.com>
@AnneCYH AnneCYH marked this pull request as ready for review October 16, 2025 10:59
a-velasco
a-velasco approved these changes Oct 16, 2025
View reviewed changes
Copy link
Copy Markdown
Contributor

@a-velasco a-velasco left a comment

Choose a reason for hiding this comment

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

Thank you @AnneCYH, this is a really useful guide.

medubelko
medubelko reviewed Oct 17, 2025
View reviewed changes
Copy link
Copy Markdown
Collaborator

@medubelko medubelko left a comment

Choose a reason for hiding this comment

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

@AnneCYH I left some suggestions. One is critical but the rest are more related to tone and user need.

Comment thread docs/how-to/custom-templates.md
Comment on lines +7 to +11
```{note}
Base template customizations can be made to your documentation.
However, they are not officially supported by the team maintaining the starter pack.
Use them at your own discretion.
```
Copy link
Copy Markdown
Collaborator

@medubelko medubelko Oct 17, 2025

Choose a reason for hiding this comment

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

I think I'd exclude this part. To me, it sounds like an unnecessary caution, which users might find discouraging.

Alternatively, we could say that users who want to do this should have experience debugging HTML templates.

Copy link
Copy Markdown
Contributor Author

@AnneCYH AnneCYH Oct 17, 2025

Choose a reason for hiding this comment

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

Tagging @SecondSkoll on this point to assess if this aligns with the plans for the epic.
Thanks.

Comment thread docs/how-to/custom-templates.md
Comment thread docs/how-to/custom-base-templates.md Outdated
Comment thread docs/how-to/custom-base-templates.md Outdated
Comment thread docs/how-to/custom-base-templates.md Outdated
Comment thread docs/how-to/custom-base-templates.md Outdated
Comment thread docs/how-to/custom-templates.md
Comment thread docs/how-to/custom-templates.md
Comment thread docs/how-to/custom-base-templates.md Outdated
Comment thread docs/how-to/custom-templates.md
@tang-mm
Copy link
Copy Markdown
Contributor

tang-mm commented Oct 17, 2025

Thanks for adding the guide, Anne! Just one note - template overwrite was briefly mentioned in Customise the setup > Adjust the header, which asks users to create a new html file. Now that we have a new how-to guide, how about combining that section with this guide?

@AnneCYH
Copy link
Copy Markdown
Contributor Author

AnneCYH commented Oct 17, 2025

Hi @tang-mm , i agree! Thanks for pointing that out.

If possible i'd like to keep this PR separate for now.
And update / merge the "Customise the setup" section with this guide once it's merged.

@AnneCYH AnneCYH requested a review from medubelko October 17, 2025 10:45
@AnneCYH
Copy link
Copy Markdown
Contributor Author

AnneCYH commented Oct 17, 2025

@medubelko, I've (hopefully) addressed your feedback. :)
Do give this another review when you can, thanks!

@AnneCYH AnneCYH merged commit f5a4b4a into main Oct 20, 2025
7 checks passed
@AnneCYH
Copy link
Copy Markdown
Contributor Author

AnneCYH commented Oct 20, 2025

thanks @medubelko and @a-velasco for your reviews and feedback!

@AnneCYH AnneCYH deleted the annecyh/custom-base-templates branch October 21, 2025 07:33
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

@a-velasco a-velasco a-velasco approved these changes

@medubelko medubelko medubelko approved these changes

@akcano akcano Awaiting requested review from akcano akcano is a code owner

@dwilding dwilding Awaiting requested review from dwilding dwilding is a code owner

@minaelee minaelee Awaiting requested review from minaelee minaelee 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

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@AnneCYH @tang-mm @a-velasco @medubelko