Project - Documentation: Difference between revisions

From Octave
Jump to navigation Jump to search
(Further writing.)
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
:''This article is deals with projects related to improving GNU Octave's documentation.  For general project ideas, see [[Projects]].''
:''This article contains project ideas related to improve GNU Octave's documentation.  For general project ideas, see [[Projects]].''


== News ==
== News ==


[[File:SeasonofDocs Logo SecondaryGrey 300ppi.png|right|200px|link=https://g.co/seasonofdocs]]
[[File:SeasonofDocs Logo SecondaryGrey 300ppi.png|right|200px|link=https://g.co/seasonofdocs]]
* GNU Octave applies for the [https://g.co/seasonofdocs 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
* GNU Octave might apply for [https://g.co/seasonofdocs Google Season of Docs (GSoD)] 2021.  Discuss about your ideas and application with us by
** [https://lists.gnu.org/mailman/listinfo/octave-maintainers <code>maintainers@octave.org</code>] mailing list (please [https://en.wikipedia.org/wiki/Posting_style#Bottom-posting bottom post]!)
** [https://lists.gnu.org/mailman/listinfo/octave-maintainers <code>maintainers@octave.org</code>] the maintainers mailing-list (please [https://en.wikipedia.org/wiki/Posting_style#Bottom-posting bottom post]!)
** [http://webchat.freenode.net?channels=octave <code>#octave</code> IRC channel] in Freenode
** [http://webchat.freenode.net?channels=octave <code>#octave</code> IRC channel] in Freenode
** updating this wiki page


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


* [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] user / developer documentation for the [https://octave.org/doc/interpreter/ Octave interpreter].


* [[Doxygen]] documentation for the internal C++ classes and external API.
* [[Doxygen]] documentation for the internal C++ classes and external API.
Line 25: Line 26:
'''Description'''
'''Description'''


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 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 and 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.
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 the Octave GUI.


'''Improvements'''
'''Improvements'''
Line 33: Line 34:
* 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.
* 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.
* 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 source-code readability of Texinfo is a burden for some developers and newcomers.  In short it is no "fun" editing those.  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 47: Line 57:
: [[User:siko1056 | Kai]]
: [[User:siko1056 | Kai]]


=== Octave's internal documentation ===


=== Octave's internal documentation ===
'''Description'''
 
[https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen], and [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] for its internal documentation.  There has been only moderate effort to add Doxygen comments to the entire code base or to create verbose descriptions for key techniques about how Octave works (here an example for [https://octave.org/doxygen/5.2/df/d4d/Macros.html important Octave macros]).  Potential reasons for this circumstance are:
# Lack of developer knowledge (code grew over 25 years), many "cryptic" macros, very complex class inheritance trees:
#* [https://octave.org/doxygen/5.2/d0/d26/classArray.html <code>liboctave/Array</code>]
#* [https://octave.org/doxygen/5.2/d6/d68/classoctave__base__value.html <code>libinterp/octave_base_value</code>]
# long Doxygen build time to see results of documentation effort
# huge size (about 2 GB), very impractical to "carry around", [https://octave.org/doxygen] slowly responding
 
Nevertheless, there is a need for internal documentation:
# Comprehensive documentation of Octave's [https://octave.org/doc/v5.2.0/External-Code-Interface.html external code interface].
# Enable newcomers (e.g. GSoC students) to study Octave's code easily.
# Avoid knowledge drain ([https://en.wikipedia.org/wiki/Bus_factor bus factor]).


Add more Doxygen comments.
'''Improvements'''


* The internal documentation should cover the following topics (a more verbose extension of [https://hg.savannah.gnu.org/hgweb/octave/file/tip/etc/HACKING.md <code>etc/HACKING.md</code>] [https://octave.org/doxygen/5.2/d1/d10/Hacking.html (html)]):
** Overview about the code base (liboctave, libinterp, libgui, ...).
** How Octave is built (necessary tools [versions], involved scripts, ...).
** The release procedure, e.g. [[6.1 Release Checklist]].
* Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''.
** The internal documentation should not be fixed on Doxygen comments only.
** As Octave's GUI makes use of qt, Doxygen might also be replaced by [https://doc.qt.io/qt-5/qdoc-index.html QDoc] with comparable markup.
** Splitting the documentation into a wiki portion, etc., is imaginable, but it must be clearly documented where to find which information, '''avoid duplication''', nobody wants to update information in more than one location.
* Technical goals are:
** Smaller memory footprint for individual documents (unlike current Doxygen with about 2 GB).
** Fast build time.
** Lightweight (existing) documentation system. No heavy preprocessing / code generation by custom scripts.
** As close to the source as necessary.  Make it difficult to update the code while not updating its documentation.  E.g. no wiki documentation for Octave's C++ files.


=== Octave's wiki ===
'''Resources'''


Flesh out this wiki.
* '''Style Guides'''
: [[C++ style guide#Doxygen]]
* '''Source code'''
: https://hg.savannah.gnu.org/hgweb/octave/file/tip/doc/doxyhtml
* '''Required skills'''
: [http://www.doxygen.nl/ Doxygen], [https://www.mercurial-scm.org/ hg], [[Building | building Octave from source]]
* '''Potential mentors'''
: [[User:siko1056 | Kai]]


[[Category:Project Ideas]]
[[Category:Project Ideas]]

Revision as of 06:46, 10 June 2020

This article contains project ideas related to improve 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 and 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 the Octave GUI.

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.
  • Document the documentation building process (e.g. rename and document involved scripts).

Long term goals / highly controversial within the community

  • Syntax, structure, and source-code readability of Texinfo is a burden for some developers and newcomers. In short it is no "fun" editing those. Consider replacement by

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

Description

Since 2013, Octave makes use of Doxygen, and etc/HACKING.md for its internal documentation. There has been only moderate effort to add Doxygen comments to the entire code base or to create verbose descriptions for key techniques about how Octave works (here an example for important Octave macros). Potential reasons for this circumstance are:

  1. Lack of developer knowledge (code grew over 25 years), many "cryptic" macros, very complex class inheritance trees:
  2. long Doxygen build time to see results of documentation effort
  3. huge size (about 2 GB), very impractical to "carry around", [1] slowly responding

Nevertheless, there is a need for internal documentation:

  1. Comprehensive documentation of Octave's external code interface.
  2. Enable newcomers (e.g. GSoC students) to study Octave's code easily.
  3. Avoid knowledge drain (bus factor).

Improvements

  • The internal documentation should cover the following topics (a more verbose extension of etc/HACKING.md (html)):
    • Overview about the code base (liboctave, libinterp, libgui, ...).
    • How Octave is built (necessary tools [versions], involved scripts, ...).
    • The release procedure, e.g. 6.1 Release Checklist.
  • Make the internal documentation obvious, easy to study and to extend, avoid effort duplication.
    • The internal documentation should not be fixed on Doxygen comments only.
    • As Octave's GUI makes use of qt, Doxygen might also be replaced by QDoc with comparable markup.
    • Splitting the documentation into a wiki portion, etc., is imaginable, but it must be clearly documented where to find which information, avoid duplication, nobody wants to update information in more than one location.
  • Technical goals are:
    • Smaller memory footprint for individual documents (unlike current Doxygen with about 2 GB).
    • Fast build time.
    • Lightweight (existing) documentation system. No heavy preprocessing / code generation by custom scripts.
    • As close to the source as necessary. Make it difficult to update the code while not updating its documentation. E.g. no wiki documentation for Octave's C++ files.

Resources

  • Style Guides
C++ style guide#Doxygen
  • Source code
https://hg.savannah.gnu.org/hgweb/octave/file/tip/doc/doxyhtml
  • Required skills
Doxygen, hg, building Octave from source
  • Potential mentors
Kai