Add a User Guide #245

llucax · 2023-11-24T10:29:07Z

This PR introduces a new User Guide top level section in the documentation explaining how to use the library in a more practical and cohesive way than just reading through the API documentation.

The bulk of the documentation is still hosted in the code itself, as docstrings, so users can still access most of user guide content directly from their IDE.

It also improves the README and the docs home page, adding a quick start section to both.

Fixes #177.

llucax · 2023-11-24T11:07:06Z

You can see the results here: https://llucax.github.io/frequenz-channels-python/v1.0-pre/user-guide/quick-start/

A few comments about stuff I found or thought about while doing this guide:

Having a higher level documentation in the module documentation makes a lot of sense IMHO, and it is a shame that this documentation is not available in the IDE, so I would like to re-consider the module structure to find a way to expose it. We can discuss elsewhere to avoid polluting this PR too much.
Having a channel module with a Channel abstract class/protocol, would also allow us to expose docs about general channel concepts that is available in IDEs too.

llucax · 2023-12-04T14:06:44Z

Rebased

shsms

I've reviewed upto the select commit. Will continue with the rest soon.

README.md

src/frequenz/channels/_anycast.py

src/frequenz/channels/_merge.py

src/frequenz/channels/_receiver.py

src/frequenz/channels/_select.py

shsms · 2023-12-06T10:18:14Z

src/frequenz/channels/_select.py

+receivers as they receive new values.
+
+It yields a [`Selected`][frequenz.channels.Selected] object that will tell you the
+source of the received message. To make sure the received value is *casted* to the


Quoting from: https://www.wordreference.com/englishusage/cast

The verb cast has several other meanings. Note that for all its meanings its past tense and past participle is cast, not ‘casted’.

Suggested change

source of the received message. To make sure the received value is *casted* to the

source of the received message. To make sure the received value is *cast* to the

looks like this one is pending.

Oh, thanks for checking, it must have been lost in some rebase because I'm sure I updated the file at some point. Updated now.

flora-hofmann-frequenz

Only a small comment from my side. Besides, I mostly agree with Sahas' additions (indicated by 'thumbs up').

src/frequenz/channels/_sender.py

shsms

Some more comments, but keeping the timer commit for the afternoon, because it is a bit big. So the last 3 commits are pending.

src/frequenz/channels/_sender.py

src/frequenz/channels/file_watcher.py

shsms

Finished reviewing. This is amazing work, Luca! very comprehensive.

src/frequenz/channels/timer.py

shsms · 2023-12-07T16:23:11Z

src/frequenz/channels/timer.py

+         1 microsecond).
+
+        This is to avoid floating point errors when performing calculations with time,
+        which can lead to very hard to reproduce, and debug, issues.


Suggested change

which can lead to very hard to reproduce, and debug, issues.

which can lead to issues that are very hard to reproduce and debug.

llucax · 2023-12-11T15:17:17Z

Updated with all the suggestions, except for the ones I left follow-up comments.

llucax · 2023-12-11T15:17:46Z

Please mark the conversation that you happy with the resolution as resolved.

shsms

Thanks luca, all looks good to me. I will approve once you fixup.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

This section includes basic installation instructions and some quick examples so users can have a very broad overview of what the library is about. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

The quick start section is reused from the README. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

We want users to be able to quickly get a feeling of the library, so it is better to also have this quick start guide in the home of the documentation. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Now the installation instruction have their own page in the user guide. We also add a tip linking to the full installation instructions in the README. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

These are mainly pages including docstrings from the source code. There are only a few pages with content of their own, and they are usually just glue to put some related docstrings together. There is one notable exception, the general channel concepts, that don't have a better home. The content of the docstring will be improved later to make the user guide more cohesive. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Add a "Characteristics" summary with the most important properties of this channel type, a diagram to show how messages are routed from multiple senders to multiple receivers, explain a bit more about what happens when buffers are full and improve and add a new example. The formatting is done having in mind this documentation is now included in the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Explain the base exceptions and the basics of error handling, including how to get the cause of an exception. This module is not publicly available, so users won't be able to access the information in IDEs for example, but it will be rendered as part of the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Explain how to use the `merge()` function and the `Merger` type on a higher level than the function documentation. This module is not publicly available, so users won't be able to access the information in IDEs for example, but it will be rendered as part of the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Give a general introduction to receivers, explaining how one usually create them, how to map values, how to handle receiving errors and how to use the low-level methods. This module is not publicly available, so users won't be able to access the information in IDEs for example, but it will be rendered as part of the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Explaining how `select()` should be used, including how to stop the iteration, how to handle errors and mentioning the exhaustiveness check. This module is not publicly available, so users won't be able to access the information in IDEs for example, but it will be rendered as part of the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Give a short introduction about how `Sender`s are created and used, including how to handle errors. This module is not publicly available, so users won't be able to access the information in IDEs for example, but it will be rendered as part of the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Add a summary of the contents of the module in the module documentation and improve the `Event` class documentation and example. The formatting is done having in mind this documentation is now included in the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Add a summary of the contents of the module in the module documentation and improve the `EventType` enum and `FileWatcher` class documentation and example. The formatting is done having in mind this documentation is now included in the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Add a quick start guide with a couple of examples in the module documentation, as well as a general explanation about missing ticks. Improve documentation of the `MissedTickPolicy` class to explain how to create custom policies, including an example. Also improve the documentation of each missed tick policy provided by the module. Improve the `Timer` class documentation to focus on how to use timers more generally, referring to the `timeout()` and `periodic()` constructors for more information, and improve both constructors documentation to explain what they are useful for and include examples. The formatting is done having in mind this documentation is now included in the User Guide. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Admonitions are not properly rendered by GitHub, so they don't look great there, but they should be readable. Without leaving an empty line they are rendered as a single paragraph, which is very messy. Since the extra indentation is interpreted as a code block, we also need to treat examples differently, as otherwise the markdown is rendered verbatim, missing syntax highlighting and other features. To overcome this issue we use simple headings for examples in the README and then include them in the documentation as admnonitions. Becuase of this we need to have more fine-grained include blocks in the README, which is also not great, but it's better than the alternative. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax · 2023-12-13T13:57:22Z

Fixup done, enabling auto-merge.

llucax requested a review from a team as a code owner November 24, 2023 10:29

llucax requested a review from Marenz November 24, 2023 10:29

llucax force-pushed the user-guide branch from 2519c51 to b7a9095 Compare November 24, 2023 10:33

llucax self-assigned this Nov 24, 2023

This comment was marked as outdated.

Sign in to view

llucax force-pushed the user-guide branch 2 times, most recently from abf9b37 to 202e0db Compare November 24, 2023 11:04

llucax requested review from shsms, matthias-wende-frequenz and daniel-zullo-frequenz November 24, 2023 11:06

llucax added this to the v1.0.0 milestone Nov 24, 2023

llucax force-pushed the user-guide branch from 202e0db to f2d52c3 Compare December 4, 2023 13:36

github-actions bot removed the part:tests Affects the unit, integration and performance (benchmarks) tests label Dec 4, 2023

llucax force-pushed the user-guide branch from f2d52c3 to 249a407 Compare December 4, 2023 14:06

github-actions bot removed the part:tooling Affects the development tooling (CI, deployment, dependency management, etc.) label Dec 4, 2023

llucax removed this from the v1.0.0 milestone Dec 5, 2023

shsms reviewed Dec 6, 2023

View reviewed changes

flora-hofmann-frequenz reviewed Dec 7, 2023

View reviewed changes

src/frequenz/channels/_sender.py Outdated Show resolved Hide resolved

shsms reviewed Dec 7, 2023

View reviewed changes

src/frequenz/channels/_sender.py Outdated Show resolved Hide resolved

src/frequenz/channels/_sender.py Outdated Show resolved Hide resolved

src/frequenz/channels/file_watcher.py Outdated Show resolved Hide resolved

src/frequenz/channels/file_watcher.py Outdated Show resolved Hide resolved

shsms reviewed Dec 7, 2023

View reviewed changes

llucax requested review from shsms and flora-hofmann-frequenz December 11, 2023 21:00

shsms reviewed Dec 13, 2023

View reviewed changes

llucax added 18 commits December 13, 2023 14:54

Add note about other platforms in the README

66cc6dd

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Add a quick start section to the README

2a8494a

This section includes basic installation instructions and some quick examples so users can have a very broad overview of what the library is about. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Add a User Guide top level section with a Quick Start

483d23d

The quick start section is reused from the README. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Add the Quick Start also to the docs home page

7405661

We want users to be able to quickly get a feeling of the library, so it is better to also have this quick start guide in the home of the documentation. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Move the installation instructions to the user guide

2907ef5

Now the installation instruction have their own page in the user guide. We also add a tip linking to the full installation instructions in the README. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Update release notes

80a2e78

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax force-pushed the user-guide branch from 79531a0 to 80a2e78 Compare December 13, 2023 13:57

llucax enabled auto-merge December 13, 2023 13:57

shsms approved these changes Dec 13, 2023

View reviewed changes

llucax added this pull request to the merge queue Dec 13, 2023

Merged via the queue into frequenz-floss:v1.x.x with commit 398f3b0 Dec 13, 2023
14 checks passed

llucax deleted the user-guide branch December 13, 2023 14:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a User Guide #245

Add a User Guide #245

llucax commented Nov 24, 2023 •

edited

Loading

This comment was marked as outdated.

llucax commented Nov 24, 2023

llucax commented Dec 4, 2023

shsms left a comment

shsms Dec 6, 2023

shsms Dec 13, 2023

llucax Dec 13, 2023

flora-hofmann-frequenz left a comment

shsms left a comment

shsms left a comment

shsms Dec 7, 2023

llucax commented Dec 11, 2023

llucax commented Dec 11, 2023

shsms left a comment

llucax commented Dec 13, 2023

	source of the received message. To make sure the received value is casted to the
	source of the received message. To make sure the received value is cast to the

	which can lead to very hard to reproduce, and debug, issues.
	which can lead to issues that are very hard to reproduce and debug.

Add a User Guide #245

Add a User Guide #245

Conversation

llucax commented Nov 24, 2023 • edited Loading

This comment was marked as outdated.

llucax commented Nov 24, 2023

llucax commented Dec 4, 2023

shsms left a comment

Choose a reason for hiding this comment

shsms Dec 6, 2023

Choose a reason for hiding this comment

shsms Dec 13, 2023

Choose a reason for hiding this comment

llucax Dec 13, 2023

Choose a reason for hiding this comment

flora-hofmann-frequenz left a comment

Choose a reason for hiding this comment

shsms left a comment

Choose a reason for hiding this comment

shsms left a comment

Choose a reason for hiding this comment

shsms Dec 7, 2023

Choose a reason for hiding this comment

llucax commented Dec 11, 2023

llucax commented Dec 11, 2023

shsms left a comment

Choose a reason for hiding this comment

llucax commented Dec 13, 2023

llucax commented Nov 24, 2023 •

edited

Loading