Migrate Sming documentation to Sphinx/readthedocs #1683
Comments
|
@mikee47 Do you know if there is a good |
|
I haven't delved too deeply into this yet, but Getting Started with Sphinx is a good starting point, especially the three references at the foot of the page (the last one is probably worth reading first An introduction to Sphinx and Read the Docs for Technical Writers). If I find anything more succinct I'll post it up. |
|
I also came across https://pandoc.org/ which may be useful converting existing markdown docs into reStructuredText. There's a cut'n'paste version here which I tried briefly https://pandoc.org/try/ |
|
So we have the Wiki documentation using markdown and we have the doxygen API documentation. Shall we convert both or only the markdown one? |
Definitely both, but I think the important thing is to get the basic structure in place so all the related stuff is together, even if it's just a load of placeholders. We can then work on it section-by-section, importing from the Wiki/doxygen output as required. The API documentation can be in its own section, but restructured so, for example, all the Streams are in one section with a related overview. The IDF docs build system uses Breathe to 'provide a bridge between the Sphinx and Doxygen documentation systems' and uses doxygen's XML output. That's more involved but we can look at that perhaps once we've decided on the basic structure. |
|
I think we're now starting to have difficulty with documentation (e.g. #1758) and keeping the Sming 3.9+ and 3.8 LTS separate and yet in sync with the code. With major stuff I've documented it separately:
Some of this has made it into the Wiki, but that's only a brief intro. and certainly don't want to have to maintain in two separate places. Many Components already have their own documentation (including Arduino Libraries) so the job of the documentation system should be to pull that together systematically. If we can get this sorted for 3.9 release then it's just a matter of diverting users to the new docs, leaving the Wiki in place for LTS. Unless anyone else has started work on this issue I intend to start working up a PR (@slaff, I've started work on porting SSL for the emulator, but I think this takes priority.) |
I am waiting anxiously for this :)
Ok, go for it. |
|
This is going a lot faster than I'd envisaged so should have something shortly. Just getting the structure right, then I'll go through everything to ensure it's consistent for 3.9. @slaff To host online documentation I guess we'll need an account on readthedocs, setting up webhooks for building etc. https://docs.readthedocs.io/en/stable/config-file/index.html. |
Working on it... we are waiting for the owner of SmingHub to grant access to read-the-docs. |
|
Meanwhile I can manually generate the documentation. For the moment we have the following page: |
|
Any ideas for what to put in the 'copyright' text in the page footers? |
|
OK, first rough draft in my repo https://github.com/mikee47/Sming.git branch is feature/sphinx-docs. Should have everything from the Wiki, converted into reStructuredText. I have not made any changes to the content yet, this is just looking at the mechanics and pulling in the reference sources. The makefile is separate at the moment, so go into All the docs. have to be under 'source', which means we can't directly pull anything in from the source trees. So, in the makefile I have a list of files to be copied into the source folder for building. At the moment it's just two files, This demonstrates that we can have a mix of reStructuredText and markdown, so we don't necessarily need to go converting everything. |
Alexey Skurydin (a.k.a anakod) and contributors or |
|
So, on my system also the following python package was required: Running What am I doing wrong? |
|
I've got sphinx version 2.1.2, maybe try a later version? |
|
The missing file is a capitalisation issue, will fix. I've stuck to a lower-case-only convention for filenames. |
The file |
|
I don't have |
Good question. Either the version that I use requires it by default (Sphinx v1.7.9) or some of the markup tags as require it. The error that I get is |
|
Ok,after looking at that page: readthedocs/readthedocs.org#2569 I guess that adding |
|
http://www.sphinx-doc.org/en/master/usage/configuration.html#confval-master_doc
I'll add it explicitly. Should probably decide which version to standardise on, http://www.sphinx-doc.org/en/master/changes.html. |
|
I've downgraded to sphinx 1.8.5 for better compatibility with breathe (for API docs). |
Let's go for 1.8 but with compatibility for 2.x whenever possible. @mikee47 Event at that early stage the documentation looks quite promising.
My thoughts on organizational changes related to the documentation SamplesWe should try to exforce documentation style for the samples. For example there should be a Readme.md file that can be used directly in the Sphinx documentation. That readme file should describe
And that should replace the Wiki page with the outdated samples and their information. Arduino LibrariesIt would be great if we can get documentation about the Arduino Libraries directly from their projects. Or just provide a list with the supported Arduino libraries and URL links of the original project(if available) IntroductionThere should be a short introduction page that is the first to be opened. Best would be if we use directly the Readme.md file in the root of the repository. Multi-arch supportShould be documented and present on the first page(s). Documentation Per VersionLast, but not least, in readthedocs we should have separate documentation per version. For example https://sming-framework.readthedocs.io/en/latest/ should lead to the latest |
|
For samples, I've used reStructuredText so we can integrate it better. Documenting the libraries is tricker because it's a mixture of various file types. I've also started migrating the API documentation, way to go though. The ESP-IDF incorporates custom roles (in |
|
I've plenty to do getting the structure and API sorted, so don't intend to do anything with the sample documentation for now. If anyone would like to lend a hand with that please do! Just check out my working branch and submit a PR with any changes you'd like. Thanks! |
|
@slaff Are we still considering these elements experimental?
|
|
|
Just reviewing docs so they're consistent with current state. |
Once you are ready with the structure me and the some of the other contributors will help you revise the documentation. |
|
I've pushed some commits, getting there I think. I need to add some notes on how to edit documentation but it's a bit less top-heavy now with the documentation sitting in each Component, Library or sample. I've added some 'magic roles' so we can just add stuff like to insert a reference to a specific sample, using the title in the document by default. I'd like to automate some other stuff, such as including a link on every sample readme page to the source code on github, for the appropriate version, but that can be done as an improvement when we've worked out how to do it! We can add doxygen information using directives from this page https://breathe.readthedocs.io/en/latest/directives.html. There is a sphinx extension called exhale which itself uses |
|
The list of Arduino Libraries is coming up short at the moment as I'm only showing those with readme files available. I'll take another look at that to see how it can be improved. |
|
As for building the docs, you need to do it from a project directory (using |
|
@mikee47 Why don't you submit your current work as PR with "[WIP] title"? We can start putting our comments there and also be able to suggest changes by sending PR to your repo. |
See [docs/README.md](https://sming.readthedocs.io/en/latest/_inc/docs/README.html) for building instructions. You can find a pre-built version based on my repo. at https://sming.readthedocs.io. It should update automatically with any changes to my `feature/sphinx-docs` branch. Please read [Contributing / Documentation](https://sming.readthedocs.io/en/latest/contribute/documentation.html) for details (source is `docs/source/contribute/documentation.rst`). See #1683 for discussion.
|
@frankdownunder @riban-bw Can you take a look at the latest sphinx documentation in the |
|
Just for info, I'm working on some documentation additions under the general topic
I hope that the new doc. system will encourage a new way of working, in that submission of samples, Components, Libraries, etc. will include better documentation which will get automatically pulled into the build - all it needs is a |
|
@mikee47 Is there anything left to do related to the documentation or I can close this discussion? |
|
@slaff I've nothing further planned for documentation structure, so yes think we can close this thread. |
|
@slaff Just to make you aware I'm still having to update the docs. manually via https://readthedocs.org/projects/sming/builds/ |
I know :(. |
|
@slaff For info got some documentation tidying up to submit (get rid of 'to be completed' in sample README files, few fixes, github links and so on). Probably have it in a day or two. |
The quality of the documentation available for the ESP-32 IDF is very good, easy to navigate and well organised. For example, take https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/vfs.html. We get a good introduction, some examples and details of the API all on the same page.
The Sming Wiki is easy to update and to submit ideas to, but it's not particularly easy to organise and hard to find what we need. Moving the Sming documentation to the new build system would offer some advantages:
I've opened this issue to hopefully start a discussion!
The text was updated successfully, but these errors were encountered: