Add Sphinx documentation framework #24185
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
darwin
documentation
|
PR #24185: Size comparison from 74296b8 to b5dde6e Increases (7 builds for bl602, cc13x2_26x2, nrfconnect, psoc6, telink)
Decreases (12 builds for bl702, cc13x2_26x2, esp32, nrfconnect, psoc6, qpg, telink)
Full report (70 builds for bl602, bl702, cc13x2_26x2, cyw30739, efr32, esp32, k32w, linux, mbed, nrfconnect, psoc6, qpg, telink)
|
Damian-Nordic
approved these changes
Dec 22, 2022
Added the basics for a sphinx-based doc portal. Added an extension `external_content` that copies the relevant doc files that are used in the documentation. This extension also modifies files while copying to adjust links and allow syntax that renders on both GitHub and Sphinx. Warnings when building the documentation have been fixed or removed. Fixes include: - Linking errors - Typos - ToC tree errors - Adding MyST configuration data - Removing anchors on the form <a name="my-anchor"></a> as they cannot be used by sphinx - Changed the GitHub rendered emoji `:heavy_check_mark:` to the ascii symbol ✔ so that it renders with Sphinx Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
Expand the markdown fences to include MyST for Sphinx syntax
like the following:
```{include} my/file.md
```
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
Add a workflow for building the documentation with Sphinx and deploy the generated html to the `project-chip/connectedhomeip-doc` repository to be used by github.io. This will overwrite the existing Doxygen documentation that is hosted there. Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
|
PR #24185: Size comparison from 63803aa to 459de44 Increases (8 builds for bl702, k32w, psoc6, telink)
Decreases (2 builds for cc13x2_26x2, nrfconnect)
Full report (70 builds for bl602, bl702, cc13x2_26x2, cyw30739, efr32, esp32, k32w, linux, mbed, nrfconnect, psoc6, qpg, telink)
|
pullapprove
bot
requested review from
andy31415,
anush-apple,
arkq,
Byungjoo-Lee,
carol-apple,
chrisdecenzo,
chshu,
chulspro,
dhrishi,
electrocucaracha,
emargolis,
franck-apple and
gjc13
pullapprove
bot
requested review from
msandstedt,
mspang,
robszewczyk,
saurabhst,
selissia,
tcarmelveilleux,
tecimovic,
tehampson,
turon,
vijs,
vivien-apple,
woody-apple,
xylophone21 and
yufengwangca
andy31415
approved these changes
Jan 4, 2023
|
PR #24185: Size comparison from e3a3aaa to 2fcfaf3 Increases (7 builds for cc13x2_26x2, esp32, nrfconnect, psoc6, telink)
Decreases (12 builds for bl602, bl702, cc13x2_26x2, nrfconnect, psoc6, qpg, telink)
Full report (70 builds for bl602, bl702, cc13x2_26x2, cyw30739, efr32, esp32, k32w, linux, mbed, nrfconnect, psoc6, qpg, telink)
|
greg-fer
approved these changes
Jan 6, 2023
Created a change in the `external_content` extension so that links to content that is also being copied to the _build folder will point to their new location instead. This enables linking to sections on other pages. This change also enables link checking for sections on other pages, and therefore also includes a fix to some previously broken section links. Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
|
PR #24185: Size comparison from 48284ae to 8778d26 Increases (12 builds for bl602, cc13x2_26x2, efr32, esp32, nrfconnect, psoc6, telink)
Decreases (4 builds for bl702, cc13x2_26x2, nrfconnect, telink)
Full report (70 builds for bl602, bl702, cc13x2_26x2, cyw30739, efr32, esp32, k32w, linux, mbed, nrfconnect, psoc6, qpg, telink)
|
|
PR #24185: Size comparison from 457f809 to c9c1cce Increases (4 builds for efr32, nrfconnect, telink)
Decreases (13 builds for bl702, esp32, nrfconnect, psoc6, telink)
Full report (71 builds for bl602, bl702, cc13x2_26x2, cyw30739, efr32, esp32, k32w, linux, mbed, nrfconnect, psoc6, qpg, telink)
|
cletnick
pushed a commit
to cletnick/connectedhomeip
that referenced
this pull request
Jan 10, 2023
* doc: add sphinx documentation framework
Added the basics for a sphinx-based doc portal.
Added an extension `external_content` that copies the relevant
doc files that are used in the documentation. This extension
also modifies files while copying to adjust links and allow
syntax that renders on both GitHub and Sphinx.
Warnings when building the documentation have been
fixed or removed. Fixes include:
- Linking errors
- Typos
- ToC tree errors
- Adding MyST configuration data
- Removing anchors on the form <a name="my-anchor"></a> as they
cannot be used by sphinx
- Changed the GitHub rendered emoji `:heavy_check_mark:` to the
ascii symbol ✔ so that it renders with Sphinx
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
* workflows: expand markdown fences in spellchecker
Expand the markdown fences to include MyST for Sphinx syntax
like the following:
```{include} my/file.md
```
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
* workflows: add docbuild workflow
Add a workflow for building the documentation with Sphinx and
deploy the generated html to the
`project-chip/connectedhomeip-doc` repository to be used by
github.io. This will overwrite the existing Doxygen
documentation that is hosted there.
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
* Restyle
* doc: move link targets to build folder
Created a change in the `external_content` extension so that
links to content that is also being copied to the _build folder
will point to their new location instead. This enables linking
to sections on other pages.
This change also enables link checking for sections on other
pages, and therefore also includes a fix to some previously
broken section links.
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
Co-authored-by: Andrei Litvin <andy314@gmail.com>
Merged
lecndav
pushed a commit
to lecndav/connectedhomeip
that referenced
this pull request
Mar 22, 2023
* doc: add sphinx documentation framework
Added the basics for a sphinx-based doc portal.
Added an extension `external_content` that copies the relevant
doc files that are used in the documentation. This extension
also modifies files while copying to adjust links and allow
syntax that renders on both GitHub and Sphinx.
Warnings when building the documentation have been
fixed or removed. Fixes include:
- Linking errors
- Typos
- ToC tree errors
- Adding MyST configuration data
- Removing anchors on the form <a name="my-anchor"></a> as they
cannot be used by sphinx
- Changed the GitHub rendered emoji `:heavy_check_mark:` to the
ascii symbol ✔ so that it renders with Sphinx
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
* workflows: expand markdown fences in spellchecker
Expand the markdown fences to include MyST for Sphinx syntax
like the following:
```{include} my/file.md
```
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
* workflows: add docbuild workflow
Add a workflow for building the documentation with Sphinx and
deploy the generated html to the
`project-chip/connectedhomeip-doc` repository to be used by
github.io. This will overwrite the existing Doxygen
documentation that is hosted there.
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
* Restyle
* doc: move link targets to build folder
Created a change in the `external_content` extension so that
links to content that is also being copied to the _build folder
will point to their new location instead. This enables linking
to sections on other pages.
This change also enables link checking for sections on other
pages, and therefore also includes a fix to some previously
broken section links.
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
Signed-off-by: Gaute Svanes Lunde <gaute.lunde@nordicsemi.no>
Co-authored-by: Andrei Litvin <andy314@gmail.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR is a continuation of #19950
Problem
This PR is a follow-up to the doc framework meeting on February 13, 2022. Goals discussed at the meeting for the doc framework setup:
Change overview
This PR introduces Sphinx as a documentation framework, and includes a workflow that builds the documentation and deploys the generated html to an external repository where it is served by github.io.
The PR consists of:
A preview of the generated page can be seen based off my fork here: https://gautesl.github.io/connectedhomeip/docs/
I will keep the page up while this PR is open.
Differences when writing docs for Sphinx
Adding files to Sphinx
Currently, everything in
/docsand all images and.mdfiles in/examplesare part of the Sphinx documentation. Everything picked up by Sphinx must be part of the ToC-tree, but in the case that a file should be part of the documentation but not part of the ToC-tree, the following can be put on top of the file:Note that this will not render as hidden on GitHub.
For a file to be a part of the ToC-tree, it must be referenced by another file with the following syntax:
See
docs/index.mdfor the root of the ToC-tree.Should a file within
/docsor/examplesnot be part of the documentation, it must be added to theexclude_patternslist located in/docs/conf.py.HTML
Nested HTML tags in markdown files will not render. If nesting is necessary to e.g. centre an image, the following syntax can be used (note that this will not render on GitHub):
For more information, see the official documentation
Links
Some existing links no longer works when used within Sphinx. To avoid rewriting all existing documentation and make the links renderable both on Sphinx and GitHub, the broken links are transformed upon building with the following rules:
[link](my/page#my_section)becomes[link](my/page).md,.png,.jpgand.svgfiles are transformed into external links to the GitHub location of that fileconf.pyunderexternal_content_link_extensionssrc,scriptsor.vscodefolders are transformed into external links to the GitHub location of that file.conf.pyunderexternal_content_link_repositoriesif you need to link to a file not included in the ToC-tree.<a name="my-anchor"></a>pattern no longer works.[See my section](#my-section)in combination with#### My Section.For more information, see the official documentation
Emojis
Emojis written on the form
:heavy_check_mark:does not render in Sphinx. Where these would be used, the unicode version of the emoji should be used directly instead.Final notes
docbuild.yamlworkflow is currently set to deploy the generated html to https://github.com/project-chip/connectedhomeip-doc, which is rendered at https://project-chip.github.io/connectedhomeip-doc/. This will overwrite the current Doxygen documentation that resides thereREADME.mdfiles include a table of contents at the very start. If desired, these may be removed in the future, as Sphinx automatically maintains a ToC for every page.Testing
make linkcheckin thedocsfolder.