Improve documentation

[jainmohit2001]

Describe the documentation you'd like

• [ ] Move usage documentation from README.md to dedicated files in docs/source
• [ ] Migrate documentation to [email protected]
• [ ] Update examples folder and migrate code to [email protected]

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.

[a-alak]

I have migrated the current documentation to be compatible with [email protected] including the examples. I am curious on the first task, I guess it is about simplification of the current README and moving more in depth parts to the documentation. Do you have any preferences or thoughts about how the documentation should be structured?

I have some thoughts on a complete update and expansion of the docs, and if there is no strong opinions otherwise I would go ahead and make the updates 😇

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.

[jainmohit2001]

Hey guys. Apologies for not getting this started soon. Been caught up with some other work. I'll be taking this up and create a plan to fix the existing documentation and improve developer onboarding.

[jainmohit2001]

We can follow the plan as mentioned below to streamline the documentation update process. The whole update will be done in various small PRs to catch errors and complete reviews in an efficient manner.

Removing existing documentation

I think just removing the existing documentation would give us a clean slate to work with. This would ensure we don't have to manage or refactor any outdated docs.

• [x] Cleanup main README.md and remove any source code from it. It should only contain brief description about the project and relevant GitHub related documents.
• [x] Cleanup existing docs/source directory and remove outdated docs. Follow the latest guide from Sphinx and start from scratch.
• [ ] Remove outdated examples from examples directory

Installation, basic examples and usage ✅

Using the sphinx documentation builder, we can initiate the docs with installation and basic usage. We should start with basic examples of CS and CSMS for both OCPP1.6 and OCPP2.0.1 versions with ~~websockets@14 and~~ websockets@15.

Deep dive

Here we will outline the inner workings of the package. We can build documentation to answer the following questions:

• How does routing work?
• What is call and call_result?
• The @on and @after handler.
• How should I create my @on and @after Action handlers? What signature should I follow for the function?
• What are different dataclasses, enums and types involved?
• What does the exceptions mean and when can I expect them in the codebase?
• Various helper functions present in the package.

How Tos

This section will help developers start building real projects.

• How to deploy a CSMS and interact with the chargers through the CSMS?
• How to use HTTP calls to interact with CSMS to send data to chargers?
• How to use a queueing technology like RabbitMQ or Redis to communicate with CSMS and send data to chargers?
• How to use Django/Flask/Asyncio/FastAPI etc. as my framework?

FAQs

This section can be built incrementally based on past issues, questions and suggestion from GitHub.

[jainmohit2001]

@a-alak @mdwcrft @proelke Let me know your thoughts here.

[a-alak]

Thanks for elaborating on your plan for the docs! I think it sounds like a really good structure.

While I definitely think it is a good idea to completely start over with the docs, I think PR #712 would be a good bridging until we can publish the new docs. #712 updates the example to compatible with ocpp v2 and websockets v15. Since the updates to both libraries there has been multiple issues from people following the docs and getting errors. Could we publish the updated version in #712, and then start deleting the old docs in the repo? Mostly to avoid all the issues that would be created otherwise.

Secondly do we really need to document websockets v13 and v14? I would imagine that people reading the docs for the first time would probably be able to install latest websockets version. And if you need to work with v13 or v14 I think one should refer to the websockets docs. We can add a note about that maybe. What do you think?

Also what do you think of the tutorials in #720 as the basic examples and usage section? Or would that be more of the deep dive? Maybe something in between 😅

[jainmohit2001]

Thanks for the suggestions. Although merging PR #712 would be good, I believe it will anyhow be overwritten soon by new docs.

Regarding websockets compatibility, I think we should atleast support v14 if not v13 in the docs, since most of the projects are still using v14.

A basic tutorial of CSMS and CS will be part of usage itself.

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.

[jainmohit2001]

I have started the work on docs revamp. I'll create a number of PRs lined up one after the another for quick review and merge them once they are aligned with the above plan.

[magaton]

Hello, I am new to this project and trying to figure out things. I see that a couple of PRs are open related to bringing docs up-to-date with the codebase. Any idea when this will be merged? Thanks!

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.

[github-actions[bot]]

This issue was closed because it has been inactive for 14 days since being marked as stale.