Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add some useful mkdocs extensions #244

Merged
merged 9 commits into from
Dec 4, 2023
Merged

Add some useful mkdocs extensions #244

merged 9 commits into from
Dec 4, 2023

Conversation

llucax
Copy link
Contributor

@llucax llucax commented Nov 23, 2023

We also make some initial use of them, but this is also in preparation of the creation of the user guide.

  • Add the mkdocs-include-markdown-plugin
  • Add the markdown-svgbob extension
  • Render Timer diagrams with svgbob
  • Reuse parts of README.md in docs/index.md

@llucax llucax requested a review from a team as a code owner November 23, 2023 15:03
@llucax llucax requested a review from Marenz November 23, 2023 15:03
@github-actions github-actions bot added part:docs Affects the documentation part:tests Affects the unit, integration and performance (benchmarks) tests part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) part:core Affects the core types (`Sender`, `Receiver`, exceptions, etc.) labels Nov 23, 2023
@llucax
Copy link
Contributor Author

llucax commented Nov 23, 2023

Based on #243, only the last 4 commits are for this PR.

@llucax llucax self-assigned this Nov 23, 2023
@llucax llucax added this to the v1.0.0 milestone Nov 23, 2023
@llucax llucax added the type:enhancement New feature or enhancement visitble to users label Nov 23, 2023
@llucax
Copy link
Contributor Author

llucax commented Nov 23, 2023

BTW, this is an example of how the diagrams are rendered:

image

This was referenced Nov 24, 2023
Merged
Open
Open
daniel-zullo-frequenz
daniel-zullo-frequenz reviewed Dec 4, 2023
View reviewed changes
Copy link
Contributor

@daniel-zullo-frequenz daniel-zullo-frequenz left a comment

Choose a reason for hiding this comment

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

I have a couple of questions related to the new diagrams. LGTM otherwise

@llucax llucax enabled auto-merge December 4, 2023 13:33
@llucax
docs: Add a macro to get a symbol's docstring summary
cc23e26 
This is useful when listing symbols, to avoid repeating the docs.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
mkdocs: Sort template features
43da02c 
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
mkdocs: Expand the navigation bar by default
2b1ec25 
Add the `navigation.expand` material template feature.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Fix Markdown dependency spacing
0a7f59d 
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Sort dependencies
f520b2a 
Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Add the mkdocs-include-markdown-plugin
7a39ebb 
This extension allows documentation to include other markdown files.
This is especially useful to be able to share parts of the README in the
generated documentation, as normally there is an overlap in the
introductory concepts.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Add the markdown-svgbob extension
79097a6 
This extension allows documentation to include ASCII diagrams/graphs
that are rendered as SVG when the documentation is generated, giving a
nicer look to the diagrams/graphs while keeping the documents readable
in text form.

This is especially useful for docstrings, are they will be seen by users
in text form, but we still want to render them nicely.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Render Timer diagrams with svgbob
a76eda1 
This uses a syntax that is more friendly with svgbob and make the
diagrams render nicely.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@llucax
Reuse parts of README.md in docs/index.md
d6b2275 
We want to also include some basic information of the project in the
documentation home page (but not all of it), so we use the include
extension to reuse some README sections.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
@github-actions github-actions bot removed the part:tests Affects the unit, integration and performance (benchmarks) tests label Dec 4, 2023
@llucax
Copy link
Contributor Author

llucax commented Dec 4, 2023

Rebased on the current v1.x.x.

@llucax llucax added the cmd:skip-release-notes It is not necessary to update release notes for this PR label Dec 4, 2023
@llucax llucax added this pull request to the merge queue Dec 4, 2023
Merged via the queue into frequenz-floss:v1.x.x with commit 834893a Dec 4, 2023
14 of 15 checks passed
@llucax llucax deleted the mkdocs-extensions branch December 4, 2023 13:50
@llucax llucax modified the milestones: v1.0.0, v1.0.0-rc.1 Mar 7, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@daniel-zullo-frequenz daniel-zullo-frequenz daniel-zullo-frequenz approved these changes

@Marenz Marenz Awaiting requested review from Marenz Marenz is a code owner automatically assigned from frequenz-floss/python-sdk-team

Assignees

@llucax llucax

Labels
cmd:skip-release-notes It is not necessary to update release notes for this PR part:core Affects the core types (`Sender`, `Receiver`, exceptions, etc.) part:docs Affects the documentation part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) type:enhancement New feature or enhancement visitble to users
Projects
Python SDK Roadmap
Status: Done
Milestone
v1.0.0-rc.1
Development

Successfully merging this pull request may close these issues.
2 participants
@llucax @daniel-zullo-frequenz