-
-
Notifications
You must be signed in to change notification settings - Fork 345
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New documentation system #1766
New documentation system #1766
Conversation
f4f96d5
to
86f5001
Compare
4e8027c
to
0838545
Compare
@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? |
@slaff Now the patching update is merged I'll rebase, tidy up and push the latest changes through. They're in my Rough list of changes:
|
99693c7
to
ae10f00
Compare
@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. |
ae10f00
to
8f2b477
Compare
@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? |
@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/. |
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). |
8f2b477
to
52e21ba
Compare
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. |
52e21ba
to
a51c92d
Compare
* Remove Wiki * Revise doxygen processing to produce XML output for `breathe` to process * Freeze sphinx at 1.8.5, version 2+ still has issues with doxygen * Add custom link roles * Pull in README files and images from Components, Libraries and Samples including submodules * Warn if README expected but not found * Add ReadTheDocs config, build has to run from conf.py
* Remove old documentation build targets (docs, wiki) * Add `docs` target to build new documentation * Add `docs-clean` target, include in `dist-clean` * Move submodule patching into build.mk and update to support whole-file replacement by creating sub-directories under '.patches' * Remove `all-submodules` target from project build, put it back into main makefile as `submodules`
d4ad26e
to
28c5ecf
Compare
I've put back the original doxygen API, but it's bound up with Sphinx so still get version control. 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. |
* README is included so doesn't need to be copied * Use m2r instead of recommonmark as it provides `mdinclude` directive * Rename `api-file` role to `source`, make relative to root directory
Should address common problems getting code to run.
28c5ecf
to
a06d6ec
Compare
@mikee47 I am planning to merge this PR. Did you plan to add something more or I should merge it today? |
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: This affects the links to Release Notes and Contributors here: |
I've updated RTD, should have docs shortly. |
Couple of issues to fix re. #1763:
I'll do a PR to address these. |
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? |
@mikee47 Do you want to submit as PR the work that you have done here: https://github.com/mikee47/Sming/tree/update/library-docs ? |
Still incomplete. Has uncovered some other stuff needs sorting as well. |
See docs/README.md for building instructions.
Please read Contributing / Documentation for details (source is
docs/source/contribute/documentation.rst
).See #1683 for discussion.