Contributing to EOS Documentation

[XHalamaX]

Hello,
as everybody know the documentation could be improved. I never worked on a Github Project so I need some help.

I forked the project, created a new branch and adjusted the optimization page. See here
Then I noticed that I maybe have to install and run sphinx and I don't understand it.

What is your preferred way of working on the documentation and could you maybe add this here https://github.com/Akkudoktor-EOS/EOS/blob/main/CONTRIBUTING.md

[b0661]

Go to your repo with your browser..

Follow the instruction given here https://docs.github.com/de/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request?tool=webui#creating-the-pull-request.

Don't worry if something goes wrong. You can close a pull request that you created at any time.

To check your documentation page before you do the pull request, you can do:

• Install the necessary packages (including sphinx)

make pip-dev

• Check the generated documentation in in your browser by:

make read-docs

If you happen to develop under Windows the following might work. Sorry can't test as I have no Windows.

python -m venv .venv
.venv\Scripts\pip install -r requirements-dev.txt
.venv\Scripts\pip install -e .
.venv\Scripts\sphinx-build -M html docs build/docs
.venv\Scripts\python -m webbrowser build/docs/html/index.html

[e-hirsch]

Had the same idea as @XHalamaX to contribute to the documentation to further improve it and share my insights. My first impulse was to work through the discussions in GitHub and collect all the information in one place. There is already so much information. I would be happy to support this procect and give little back to the community.

@XHalamaX Maybe we should coordinate so that we don't work on the same topics. My idea was to create a high level view on what EOS is, what it needs to work and how it works in principle as soon as I have set everything up and understand how to work with GitHub and Sphinx. As you are much deeper into the details of what is needed to start the optimization it would be great to start with that. Your comments helped everybody so much in understanding and start with the setup. Just an idea...

Thanks @b0661 for the hints how to contribute and how to install sphinx.

Another question for me would be if we should start with the German documentation which would be much easier (at least for me). As far as I can see it seems that most people who are currently interested in EOS are from Germany or are speaking German.

Does anyone have a problem with discussing in German and English as everyone likes? Would make things much easier and the EVCC project is a good example that this works seamlessly. I'm asking because it's not my project and don't want to be disrespectful.

[XHalamaX]

I didn't proceeded with the documentation yet. Just worked on a newer version of my Node-Red EVCC/EOS integration and I have to fix some timezone issues. So you can just start and maybe pickup what I did here https://github.com/XHalamaX/EOS/blob/documentation_update/docs/akkudoktoreos/optimization.md

In generel, we could work on my fork to improve the documenation. Then this team here does not to do anything. We can organise the tasks and documentation issues in my repo. But maybe there are better options...

The language should be decided by the core team as well. But I think we should proceed with english. You can always write it in german and let ChatGPT or something like that translate the stuff.

[b0661]

Another question for me would be if we should start with the German documentation which would be much easier (at least for me). As far as I can see it seems that most people who are currently interested in EOS are from Germany or are speaking German.

The concept of sphinx for translation is to have a source language. The source text is split into sentences/ words which are then translated. So a source language documentation has to be available which IMHO should be in English. Maybe there are other tools for Sphinx and translation that I´m not aware of and that may support other ways to generate translations.

In generel, we could work on my fork to improve the documenation. Then this team here does not to do anything. We can organise the tasks and documentation issues in my repo. But maybe there are better options...

Another way is that we create a feature branch for documentation in the Akkudoktor repo on which you can work. This way the documentation work gets a better visibility in the project. We can also add you as a maintainer for this , if you like.

[XHalamaX]

Another way is that we create a feature branch for documentation in the Akkudoktor repo on which you can work. This way the documentation work gets a better visibility in the project. We can also add you as a maintainer for this , if you like.

Yes, please

[e-hirsch]

Think via feature branch would be the easiest way. And adding as maintainer would be great.

[b0661]

There is now this branch https://github.com/Akkudoktor-EOS/EOS/tree/feature/documentation for you.

I ask @Lasall to add you for maintenance for the feature branch.

[Lasall]

Btw. you can also look at the automatically generated Sphynx documentation from your feature branch: https://akkudoktor-eos.readthedocs.io/en/feature-documentation/ (check the build status here: https://app.readthedocs.org/projects/akkudoktor-eos/builds/?version__slug=feature-documentation&state=&version__type=)

[e-hirsch]

Finally I got most things set up and working. But I must say that it was a steep learning curve. It took me several hours to go through the documentation of Sphinx, VS Code and various plug-ins. In comparison documenting with Confluence is a pleasure ;-).

I was able to clone the repository and can switch to the feature-documentation branch. Adding a new file and also add it in the index.md file and re-generating the html documentation with Sphinx worked well. What I've not tried up to now is to push the file to GitHub.

I've played around with markup and with reStructuredText. I like the possibilities that reStructuredText offers. But even after spending hours I wasn't able to get the preview via esbonio plugin in VS Code to work while the md preview works fine. So I decided to go with normal markup for now as this allows a smooth workflow. Is this the reason for not using rst in the docs until now?