Large rewritting of docs

[a-alak]

Not ready for merge! This is a draft/suggestion. Would love your thoughts and feedback.

Changes included in this PR

First draft. Includes a restructuring of the docs setup, addition of multiple doc dependencies (sphinx_inline_tabs, myst_parser, sphinx_copybutton, furo theme), change of theme. Currently the biggest addition is tutorials. The API reference is mostly an AI created draft to get started. Includes suggestions on possible additions (how-to guides and topic guides).

Current behavior

There has been multiple request for updates/expansion of the documentation.

New behavior

Suggesting new documentation theme and a couple of extensions.

Impact

Only changes to the docs.

Checklist

1. [x] Does your submission pass the existing tests?
2. [ ] Are there new tests that cover these additions/changes?
3. [x] Have you linted your code locally before submission?

[mdwcrft]

Great contribution thank you! We'll need some time to review this and may suggest to break into a few separate PRs but it looks like a big improvement on the current docs

Is this now a duplicate of #712? If so please close one of them and we'll focus on the other

[abhasMGL]

I am not an active contributor or the codeowner, but definitely a great PR @a-alak Documentation is detailed and thorough for any person wanting to implement OCPP in python.

[a-alak]

Great contribution thank you! We'll need some time to review this and may suggest to break into a few separate PRs but it looks like a big improvement on the current docs

Is this now a duplicate of #712? If so please close one of them and we'll focus on the other

Ahh sorry, my mistake. Seems like I accidentally pushed this change to #712 as well. #712 was mostly meant to be quick fixes to the current documentation to make it comply with websockets v15 and ocpp v2. This is more of rewrite of the documentation and structure.

I will try to revert #712 to the originally changes for that PR. Might be a relevant bridge until this one is complete so we can avoid issues about version compatibility when people follow the current documentation.

[jainmohit2001]

Thanks for the contributions @a-alak. Loved the effort you have put here. We can improve the documentation by following a simple principle: Keep it minimal.

Documentation, just like code, is a maintenance nightmare. Although I understand documenting important aspects of the functioning of the library, I think we should restrain ourselves from documenting everything.

The codebase is built in a such way that it is quite easy to understand the workflow and pieces used just by looking at the code. Creating a documentation for such pieces is not preferred. E.g., Types of exceptions and their description. The execptions.py contains enough information for anyone to understand them in detail. Creating a doc for that is not necessary.

Please don't take my suggestions as critical criticism but merely an improvement on your effort.

Happy to point out what we should remove from documentation and what should be kept.

[a-alak]

Good point @jainmohit2001 ! And to be totally honest and transparent the API Reference is AI generated, and I only adjusted minimally on that section. Is it correctly understood that you suggest to drop the API Reference section?

I would then suggest to have some kind of overview of CSMS-initiated calls vs. Chargepoint-initiated calls referring to the actual data classes in this library. I know this is redundant when taking in to account the actual OCPP specification. However the specification can be hard to read and get an overview on. I am thinking in a developer workflow you would have to balance 1) ocpp docs 2) OCPP specification 3) ocpp repo to see the dataclasses (completions in IDEs can take care of it, but I find my self often looking at the call and call_result modules). I would imagine having a simple reference to the dataclasses combined with an overview of which are sent by the CSMS and which are sent by the chargepoint (plus maybe feature profiles) would enable a newcomer to work with only their IDE and the ocpp docs. What do you think, is it out-of-scope for this documentation or could it be relevant?

The main thing I did here was to rewrite the tutorials for implementing a CSMS and a Chargepoint, would love to hear your thoughts on that?

Also what do you think about the suggestion of having sections explaining how to implement this library in different web frameworks? I often see questions regarding this and thought it could be nice to have it in the docs. Did not write any of it yet, but added it to the docs structure.