apache / apache/nuttx

Documentation roadmap

Open
#1,638 20 comments 0 reactions 0 assignees View on GitHub
Area: Documentation
Dominant language
C
Stars
4k
Forks
1.7k
Avg merge
1d 17h
Merged PRs (30d)
237

Description

These are the pending tasks to complete the new documentation:

- [ ] fill supported boards section using content from current README files: this can be done by either:
* convert all READMEs to Markdown and use `mdinclude`
* create dedicated RST files for each board inside Documentation/. In this case, READMEs should only contain technical information not appropriate for Documentation.
- [ ] autogenerate the list of supported platforms based on all boards existing on the repo
- [ ] allow the docs to pickup information from the application repo so that applications are also documented (or at least initially, listed)
- [ ] look into defining a workflow which would build documentation for each PR somewhere (github pages for the nuttx repo?) so that previewing a PR is simple.
- [x] devise the CI workflows necessary to have this published on nuttx website. documentation should be deployed for master and for every tagged release. The documentation itself allows to choose which version to read (see mockup dropdown just above search field in documentation)

Various parts of the documentation require writing new content (possibly already existing in other external sources):
- [ ] introduction -> development environments: check if this is still up to date and revise whether any given particular toolchain should be recommended. this also requires a bit of rewrite to be more like a documentation and not simply a report of toolchain support status.
- [ ] update contributing sections with information from here: https://github.com/apache/incubator-nuttx-apps/pull/378 (acceptable licenses)
- [ ] disable autosectionlabel and correct all references which use it (add manual labels instead)
- [ ] start looking into the wiki, looking for information that should be converted to documentation of a subsystem not currently documented and for guides for the corresponding section. providing documentation for a subsystem should be prioritized over just providing a guide covering a particular use case.
- [ ] Find correct name for one of these two sections, which were named the same in original docs:
* https://nuttx.apache.org/docs/latest/reference/user/01_task_control.html
* https://nuttx.apache.org/docs/latest/reference/user/03_task_control.html
- [x] quickstart: this is a very important section for newcomers. this guide should give instructions on how to try nuttx on a commonly available board with good support for nuttx (some stm32 nucleo/discovery?).
- [x] introduction -> trademarks: revise this. it mentions NuttX to be trademarked which I'm not sure it is still true.
- [x] releases: remove section, simply link to relevant part of website from elsewhere (intro?)
- [x] solve warnings about duplicated declarations: this means that the same function is documented twice in the documentation. this should be fixed so a single documentation is done and references to it added when necessary
- [x] Update Pipfile.lock to match requirements.txt (the latter has correct versions)
- [x] update all links to point to new docs and URLs (related to #883)
- [x] add support for tabbed examples
- [x] fix all broken links (use `make linkcheck` within `Documentation` to make Sphinx check all links)

Feel free to suggest new tasks or discuss the ones already listed.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.