Proposal: Create read the docs Documentation

[fabianmuehlberger]

Hi, I would like to propose to create an official documentation using Readthedocs. This would certainly help others working with your API and bring more contributions to this platform.

Why readthedocs (rtd) ? It is widely used for documenting projects and is highly customizable and works with multiple languages.

I created a basic example how the TMC-API documentation could look like, using rtd, sphinx doxygen for generating the documentation. This workflow allows automated generation of documentation based on the doxygen comments in the code itself and therefore version controlled docs. Additionally, sphinx is used to write more descriptive with reStructuredText than plain doxygen comments, and can create a more user-friendly documentation.

The documentation I made is mostly autogenerated with a few doxygen styled comments for a few functions for testing, but this is nearly fully autogenerated and can be generated by clicking one button or automated via GitHub actions.

I hope this idea is of interest to you and helps develop this amazing hardware platform!

Best, Fabian

[trinamic-ed]

Hello Fabian,

we discussed the documentation topic internally.

E.g. for our iolink python package, we made a readthedocs.io doku some time ago.

We've seen that you started a documentation using doxygen. In the moment it seems to be a copy of the C-code function header, there must be added more to make it more usable.

In the moment we do not focus on the doku. We will update the source code in the next weeks/month to make it easier usable also for Arduino and Raspi, so the TMC-API code will change in the next time and also the use inside the TMC-EvalSystem.

Best regards, Enrico

[fabianmuehlberger]

Hey, Thank you for the reply, these are good news. As I mentioned in my proposal, the work I did was purely a proof of concept since I had no prior experience with readthedocs.

Since I had no intention to change the code base or just doxygen comments I left it fully autogenerated with some test how to structure the doc with .rst files.

I would also prefer a documentation that is not only the autogenerated doxygen but a more descriptive implementation with examples and helpful information as well as explaining the overall concept of the API.

I will take down the readthedocs again, since it is misleading. If I can help in any way, let me know, I am happy to contribute. Especially because I am working on an implementation using the TMC-API for ESPhome using the esp-idf.

Information about the upcoming changes would be very appreciated, since 2 people are currently putting a lot of work in it!

[fabianmuehlberger]

Hey @trinamic-ed
Are there any news on the changes to the TMC API, as you mentioned in your answer?

In the moment we do not focus on the doku. We will update the source code in the next weeks/month to make it easier usable also for Arduino and Raspi, so the TMC-API code will change in the next time and also the use inside the TMC-EvalSystem.

It would be very helpful to me, if you could provide some estimation when you will be able to release your update, and what parts are up for change.

Best Fabian