New documentation system

[mikee47]

See docs/README.md for building instructions.

Please read Contributing / Documentation for details (source is docs/source/contribute/documentation.rst).

See #1683 for discussion.

[slaff]

@mikee47 we can add the initial version of the documentation. It is not complete but the structure looks good. Did you plan to add anything more here?

[mikee47]

@slaff Now the patching update is merged I'll rebase, tidy up and push the latest changes through. They're in my dev/sphinx-docs branch and that version is available on readthedocs if you want to have a browse.

Rough list of changes:

• README files may be either README.rst or README.md
• Every Component, Library and Sample page gets an automatic 'references' section at the bottom, plus a list of any environment variables it defines. The actual README is included, and is now simpler as it doesn't need to bother with any of that.
• Fixes to doxygen comments (gets rid of a load of warnings/errors)
• Add section on patching to the 'building' docs.

[mikee47]

@slaff I'm reasonably OK with how the build system is working, so this morning taking some time to read through from the top and fix anything I come across. I'll check them in later today, up to you whether to include them in the initial merge or leave it for another PR.

[slaff]

@mikee47 With the latest update the list of sample project is not showing any longer. The list of Arduino Libraries is not showing either. What am I doing wrong?

[mikee47]

@slaff You've done nothing! RTD doesn't always track changes very well so I wiped and rebuilt it manually.

[mikee47]

@slaff Once you've merged this I'll update the RTD project to point to the real repo. I've added you as a maintainer so you should be able to make changes https://readthedocs.org/projects/sming/.

[slaff]

https://sming.readthedocs.io/en/latest/api/index.html: Concerning the API - is there something planned to integrate the current API docs (the ones that doxygen generates).

[mikee47]

Yes, more work required there. There should be stuff under Streams now (reverted a change made during later updates) so that's the sort of thing. It does need breaking up more logically though so is a project all in itself.

[mikee47]

I've put back the original doxygen API, but it's bound up with Sphinx so still get version control.
I've also enabled graphs to assist with navigating and understanding class hierarchies and other relationships.

Whilst there are a number of extensions which could help, there is no easy way to generate a similar level of information within Sphinx. In fact, the two sets of documentation are complimentary and serve different purposes.

Note that any code docs we pull into Sphinx using the breathe extension won't be linked to the API section.

[slaff]

@mikee47 I am planning to merge this PR. Did you plan to add something more or I should merge it today?

[mikee47]

I'm all finished for now. There is one (very) minor bug that I'm aware of, which affects markdown documents containing links to other (local) markdown. It's been raised already:

miyakogi/m2r#41 (comment)

This affects the links to Release Notes and Contributors here:
https://sming.readthedocs.io/en/latest/_inc/Sming/Libraries/IR/index.html

[mikee47]

I've updated RTD, should have docs shortly.

[mikee47]

Couple of issues to fix re. #1763:

• Didn't pick up changes, so did a manual wipe/rebuild. Will investigate.
• Missing title in README for MCP23008. Probably needs clarifying in documentation.

I'll do a PR to address these.

[mikee47]

* Didn't pick up changes,

Can't see any issue with the build system, so I'm guessing it's because the webhook isn't working yet. I guess when it is we'll need to move things into another RTD account?

[slaff]

@mikee47 Do you want to submit as PR the work that you have done here: https://github.com/mikee47/Sming/tree/update/library-docs ?

[mikee47]

Still incomplete. Has uncovered some other stuff needs sorting as well.