Project - Documentation: Difference between revisions
m (Improve summary.) |
(→Octave's interpreter documentation: Add more content.) |
||
| Line 33: | Line 33: | ||
* Check for inconsistencies in the manual, e.g., outdated descriptions, awkwardly ordered information, ... | * Check for inconsistencies in the manual, e.g., outdated descriptions, awkwardly ordered information, ... | ||
* More examples and demo files for using each Octave command. | * More examples and demo files for using each Octave command. | ||
* More figures to demonstrate Octave's plotting capabilities. | * More figures to demonstrate Octave's plotting capabilities, but regard doc size and building time. | ||
* | * Think about a superior organization/splitting of the manual. Currently it covers many topics interleaved: user manual, function reference, developer guide. | ||
** Idea for a function reference including [[Octave Forge]] packages: https://octave.sourceforge.io/docs.php (unmaintained) | |||
* Document the documentation building process (e.g. rename and document involved scripts). | |||
'''Long term goals / highly controversial within the community''' | |||
* Syntax, structure, and readability of Texinfo is a burden for some developers and newcomers. Consider replacement by | |||
** [https://commonmark.org/ CommonMark/Markdown] | |||
** [https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html reStructuredText] / [https://www.sphinx-doc.org/ Sphinx] | |||
** ... | |||
'''Resources''' | '''Resources''' | ||
| Line 46: | Line 55: | ||
* '''Potential mentors''' | * '''Potential mentors''' | ||
: [[User:siko1056 | Kai]] | : [[User:siko1056 | Kai]] | ||
=== Octave's internal documentation === | === Octave's internal documentation === | ||
Revision as of 08:03, 21 April 2020
- This article contains project ideas related to improve GNU Octave's documentation. For general project ideas, see Projects.
News
- GNU Octave applies for the Google Season of Docs (GSoD) 2020. Potential participation will be announced on May 11, 2020 at 12:00 UTC. Discuss about your ideas and application with us by using Octave's
maintainers@octave.orgmailing list (please bottom post!)#octaveIRC channel in Freenode
Existing Documentation
- For a comprehensive list see Publications about Octave.
- Texinfo user documentation for the Octave interpreter.
- Doxygen documentation for the internal C++ classes and external API.
Suggested Projects
Octave's interpreter documentation
Description
The documentation for the interpreter is presumably the oldest, long grown documentation of the GNU Octave project. It is mostly written in Texinfo and strongly interleaved in the Octave build process, i.e., it is necessary to build Octave from source to generate included figures. Additionally, large portions of the Texinfo source are auto generated to stay close to the source code to avoid stale documentation. A special type of this auto generation are the so-called "docstrings", which are extracted from both C++ files and Octave's own script files (m-files).
The resulting Texinfo sources are translated to Info, PDF, PostScript, and HTML, whereas the HTML is further processed to match the QT Help Framework, which is displayed in Octave.
Improvements
- Check for inconsistencies in the manual, e.g., outdated descriptions, awkwardly ordered information, ...
- More examples and demo files for using each Octave command.
- More figures to demonstrate Octave's plotting capabilities, but regard doc size and building time.
- Think about a superior organization/splitting of the manual. Currently it covers many topics interleaved: user manual, function reference, developer guide.
- Idea for a function reference including Octave Forge packages: https://octave.sourceforge.io/docs.php (unmaintained)
- Document the documentation building process (e.g. rename and document involved scripts).
Long term goals / highly controversial within the community
- Syntax, structure, and readability of Texinfo is a burden for some developers and newcomers. Consider replacement by
Resources
- Style Guides
- Source code
- Required skills
- Potential mentors
Octave's internal documentation
Add more Doxygen comments.
Octave's wiki
Flesh out this wiki.