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

Backport documentation generation to v0.10.x #35

Merged
merged 17 commits into from
Nov 4, 2022
Merged

Backport documentation generation to v0.10.x #35

merged 17 commits into from
Nov 4, 2022

Conversation

leandro-lucarella-frequenz
Copy link
Contributor

See #25 for details.

  • ci/labeler: Add missing noxfile.py
  • Use MkDocs to build the documentation
  • Move copyright and license as code comments
  • docs: Add missing file format to examples
  • docs: Add some useful cross-references.
  • docs: Indent examples
  • Use forward type annotations
  • docs: Indent "Returns:" properly
  • docs: Improve formatting of some symbols
  • docs: Make some minor improvements
  • docs: Add site version via mike
  • ci: Remove unnecessary checkout of submodules
  • ci: Build and publish documentation
  • Run normal linting on noxfile.py
  • Run mypy on noxfile.py and be more restrictive
  • ci: Add contents permission to publish-docs

llucax added 17 commits November 4, 2022 10:35
@llucax
ci/labeler: Sort file patterns
e67c101 
Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
ci/labeler: Add missing noxfile.py
e6cbe94 
Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
Use MkDocs to build the documentation
82ed635 
The documentation is generated using MkDocs, using the Material theme
plus mkdocstrings (and a few minor supporting extensions) to build the
API documentation extracted from code comments.

For now the home page is a place holder, and the supporting script
`docs/mkdocstrings-autoapi.py` should eventually be moved to a common
repository.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
Move copyright and license as code comments
3a1dea3 
When generating the documentation, the License and Copyright text
appears on every module. It might be confusing for users if the license
applies to the code or the documentation.

This commit just moves the copyright notice and license specification as
a regular comment instead of putting it into the docstring that gets
rendered as documentation.

This was automatically adjusted using:

```sh
find -name '*.py' -not -path './.*' \
	| xargs sed -i '1 i\# License: MIT\n# Copyright © 2022 Frequenz Energy-as-a-Service GmbH\n'
find -name '*.py' -not -path './.*' \
	| xargs sed -zi 's/\n\?\(Copyright\|License\)\n[^\n]*\n\n\?//g'
```

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
docs: Add missing file format to examples
e285652 
Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
docs: Add some useful cross-references.
56668d1 
Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
docs: Indent examples
6d4516f 
This is needed to get them properly rendered and in a collapsable way.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
Use forward type annotations
ce4d0e6 
Besides improving code legibility, they are necessary for the rendered
documentation to be properly cross-referenced (otherwise the types
appear just as a string, without links).

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
docs: Indent "Returns:" properly
c991873 
Then "Returns:" uses more than one line, it should be indented one level
more to mark the continuation of one return specification, as it is
possible to have multiple return specifications.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
docs: Improve formatting of some symbols
706b479 
Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
docs: Make some minor improvements
5da37b7 
A few comments are rephrased or added or removed in the hopes to make
the documentation more reable or easier to understand.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
docs: Add site version via mike
4c84e22 
mike is a tool to keep several versions of a MkDocs site.

Please see the project documentation for more info:
https://github.com/jimporter/mike

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
ci: Remove unnecessary checkout of submodules
b84479c 
Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
ci: Build and publish documentation
e69c191 
For pull requests the documentation is built and uploaded as an
artifact, so it can be manually checked.

For pushes, the documentation is built and published.

When pushing to a branch, if it is the default branch, then the
published version is called "next". At some point we might want to
consider having multiple vMAJOR.MINOR-dev documentation generated, but
will come when/if we have multiple vMAJOR.MINOR being maintained. For
now if a branch other than the default branch is pused to, nothing will
be published.

When pushing a new tag, if it is a pre-release tag (includes a `-`),
then the documentation is not published (again it could be published
once we have vMAJOR.MINOR-dev versions of the documentation). Otherwise
the documentation is published with version vMAJOR.MINOR and a vMAJOR
alias is added. If the MAJOR is the same as the default branch,
a "latest" alias is added/updated to that version too.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
Run normal linting on noxfile.py
0962e7a 
Also fix issues found while running the linting.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
Run mypy on noxfile.py and be more restrictive
eb1a36e 
There is no reason to ignore imports, that only makes checking the types
weaker.

To be able to check types in a more strict way, we need to use packages
(-p) to avoid errors about having the same file in 2 packages
(src.frequenz.channels and frequenz.channels), so we need to translate
directory to package when running on `src`. Also we need to check
individual files separately.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@llucax
ci: Add contents permission to publish-docs
0003ad2 
Without this permissions the job can't publish GitHub Pages.

Signed-off-by: Leandro Lucarella <leandro.lucarella@frequenz.com>
@leandro-lucarella-frequenz leandro-lucarella-frequenz added part:docs Affects the documentation type:enhancement New feature or enhancement visitble to users labels Nov 4, 2022
@leandro-lucarella-frequenz leandro-lucarella-frequenz added this to the v0.10.1 milestone Nov 4, 2022
@leandro-lucarella-frequenz leandro-lucarella-frequenz requested a review from a team as a code owner November 4, 2022 09:45
@github-actions github-actions bot added part:channels Affects channels implementation part:tests Affects the unit, integration and performance (benchmarks) tests part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) labels Nov 4, 2022
@leandro-lucarella-frequenz leandro-lucarella-frequenz changed the title ci/labeler: Sort file patterns Backport documentation generation to v0.10.x Nov 4, 2022
@sahas-subramanian-frequenz
Copy link
Contributor

Does this push to the gh-pages branch as well? Would it write to a different directory, so that it doesn't overwrite the docs for the other versions?

@leandro-lucarella-frequenz
Copy link
Contributor Author

leandro-lucarella-frequenz commented Nov 4, 2022 •
edited
Loading

Does this push to the gh-pages branch as well? Would it write to a different directory, so that it doesn't overwrite the docs for the other versions?

Yes, this is what mike is for. It basically checks-out the current gh-pages branch, generates the docs in the directory specified by <version> in mike deploy <version>, overwriting that version but without touching other directories, so documentation for other versions will be left untouched, then commits. If --push is used, it will also push, but we could also push manually using git.

Then it uses aliases for versions. I'm using latest to point to the last stable release, which is also the default (what you get if you go to the / without pointing to a specific version). I'm also using v0 to point to the latest v0.x and generating only vMAJOR.MINOR versions (so no specific docs for point releases).

mike set-default <version> just creates a index.html with a redirection. You can see this in the gh-pages branches history; here is the commit setting the default: 27dab7b.

@leandro-lucarella-frequenz
Copy link
Contributor Author

FYI one check is missing because we didn't support Python 3.11-dev in v0.10.x, I don't think it is worth changing. Maybe we can add a dummy ci job that depends on all the tests we want the PRs to pass and only have that job as a requirement for PRs, so this doesn't happen while we add/remove python versions...

@sahas-subramanian-frequenz
Copy link
Contributor

because we didn't support Python 3.11-dev

we also need to switch to the stable version of 3.11, now that it has been released.

@leandro-lucarella-frequenz
Copy link
Contributor Author

we also need to switch to the stable version of 3.11, now that it has been released.

Yeah, I was planning to do so after all this.

@leandro-lucarella-frequenz leandro-lucarella-frequenz merged commit a9e3d63 into frequenz-floss:v0.10.x Nov 4, 2022
@leandro-lucarella-frequenz leandro-lucarella-frequenz mentioned this pull request Nov 4, 2022
Closed
@leandro-lucarella-frequenz leandro-lucarella-frequenz deleted the v0.10.x-docs branch November 4, 2022 12:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@sahas-subramanian-frequenz sahas-subramanian-frequenz sahas-subramanian-frequenz approved these changes

@ela-kotulska-frequenz ela-kotulska-frequenz Awaiting requested review from ela-kotulska-frequenz ela-kotulska-frequenz was automatically assigned from frequenz-floss/python-sdk-team

Assignees

@leandro-lucarella-frequenz leandro-lucarella-frequenz

Labels
part:channels Affects channels implementation 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.) type:enhancement New feature or enhancement visitble to users
Projects
None yet
Milestone
v0.10.1
Development

Successfully merging this pull request may close these issues.
3 participants
@leandro-lucarella-frequenz @sahas-subramanian-frequenz @llucax