Project - Documentation: Difference between revisions

From Octave
Jump to navigation Jump to search
(→‎Projects: First draft for suggested projects.)
(Further writing.)
Line 9: Line 9:


== Existing Documentation ==
== Existing Documentation ==
:''For a comprehensive list see [[Publications about Octave]].''  
:''For a comprehensive list see [[Publications about Octave]].''


* [[Doxygen]] documentation for the C++ classes.
* [https://www.gnu.org/software/texinfo/ Texinfo] user documentation for the [https://octave.org/doc/interpreter/ Octave interpreter].


* [https://www.gnu.org/software/texinfo/ Texinfo] documentation for the [https://octave.org/doc/interpreter/ Octave interpreter].
* [[Doxygen]] documentation for the internal C++ classes and external API.


* This wiki:
* This wiki:
Line 23: Line 23:
=== Octave's interpreter documentation ===
=== Octave's interpreter documentation ===


The documentation for the interpreter is presumably the oldest, long grown documentation of the GNU Octave project.  It would be useful to have lots more examples, to not have so many forward references, and to not have very many simple lists of functions.
'''Description'''


Add more demo files.
The documentation for the interpreter is presumably the oldest, long grown documentation of the GNU Octave project.  It is mostly written in [https://www.gnu.org/software/texinfo/ Texinfo] and strongly interleaved in the [[Building | 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 [[Help text | "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 [https://doc.qt.io/qt-5/qthelp-framework.html 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.
* Splitting the manual into an descriptive function overview and a function reference, similar to the unmaintained one at [https://octave.sourceforge.io/docs.php Octave Forge].  Currently, both are interleaved.
'''Resources'''
* '''Style Guides'''
: [[Contribution guidelines#Coding style]]
* '''Source code'''
* '''Source code'''
: https://hg.savannah.gnu.org/hgweb/octave/file/tip/doc/interpreter
: https://hg.savannah.gnu.org/hgweb/octave/file/tip/doc/interpreter

Revision as of 19:08, 17 April 2020

This article is deals with projects related to improving GNU Octave's documentation. For general project ideas, see Projects.

News

SeasonofDocs Logo SecondaryGrey 300ppi.png

Existing Documentation

For a comprehensive list see Publications about Octave.
  • 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.
  • Splitting the manual into an descriptive function overview and a function reference, similar to the unmaintained one at Octave Forge. Currently, both are interleaved.

Resources

  • Style Guides
Contribution guidelines#Coding style
  • Source code
https://hg.savannah.gnu.org/hgweb/octave/file/tip/doc/interpreter
  • Required skills
Texinfo, hg, building Octave from source
  • Potential mentors
Kai


Octave's internal documentation

Add more Doxygen comments.


Octave's wiki

Flesh out this wiki.