Project - Documentation: Difference between revisions

Jump to navigation Jump to search

Project - Documentation (edit)

Revision as of 01:38, 16 December 2021

9,835 bytes added ,  16 December 2021
→‎News: Update communication channels.
(Remove wiki stub.)
(→‎News: Update communication channels.)
(15 intermediate revisions by 4 users not shown)
Line 4: Line 4:


[[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)] in 2022.  Examples of successful projects from other organizations can be found at:
** [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]!)
** latest: [https://developers.google.com/season-of-docs/docs/participants GSoD Current Participants List]
** [http://webchat.freenode.net?channels=octave <code>#octave</code> IRC channel] in Freenode
** 2020: [https://developers.google.com/season-of-docs/docs/2020/participants GSOD 2020 Participants Archive]
 
* Discuss about your ideas and application with us by:
** [https://octave.discourse.group/ GNU Octave User and Developer Forum]
** [[IRC]]
** 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 30:
'''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'''


* Easy but long task: Every function description should mention the output variable if there is one. See bug {{bug|61681}} and [[#Working list of functions needing output variables]] below.
* 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.
Line 40: Line 46:
'''Long term goals / highly controversial within the community'''
'''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
* 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://commonmark.org/ CommonMark/Markdown]
** [https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html reStructuredText] / [https://www.sphinx-doc.org/ Sphinx]
** [https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html reStructuredText] / [https://www.sphinx-doc.org/ Sphinx]
Line 60: Line 66:
'''Description'''
'''Description'''


[https://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9 Since 2013], Octave makes use of [http://www.doxygen.nl/ Doxygen] for it's internal documentation.  Ever since, there has been 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:
[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:
# 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/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>]
#* [https://octave.org/doxygen/5.2/d6/d68/classoctave__base__value.html <code>libinterp/octave_base_value</code>]
# long build time to see results of documentation effort
# 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
# huge size (about 2 GB), very impractical to "carry around", [https://octave.org/doxygen] slowly responding


Nevertheless, there is a need for internal documentation:
Nevertheless, there is a need for internal documentation:
Line 76: Line 82:
* 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)]):
* 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, ...).
** Overview about the code base (liboctave, libinterp, libgui, ...).
** How Octave is build (necessary tools [versions], involved scripts, ...).
** How Octave is built (necessary tools [versions], involved scripts, ...).
** The release procedure, e.g. [[6.1 Release Checklist]].
** The release procedure, e.g. [[6.1 Release Checklist]].
* Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''.
* Make the internal documentation '''obvious, easy to study and to extend, avoid effort duplication'''.
Line 86: Line 92:
** Fast build time.
** Fast build time.
** Lightweight (existing) documentation system. No heavy preprocessing / code generation by custom scripts.
** 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 it's documentation.  E.g. no wiki documentation for Octave's C++ files.
** 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'''
'''Resources'''
Line 98: Line 104:
* '''Potential mentors'''
* '''Potential mentors'''
: [[User:siko1056 | Kai]]
: [[User:siko1056 | Kai]]
==Appendix==
===Working list of functions needing output variables===
See bug {{bug|61681}}. The docstrings in following core octave functions do not explicitly specify an output variable.  While htis may be appropriate for some, many should have the output variable added.  For example:
<code>## @deftypefn {} {} sind (@var{x})</code>
should be something like:
<code>## @deftypefn {} {@var{y} =} sind (@var{x})</code>
Please delete or strikethrough the file when you've confirmed it has been updated via a patch or code push noted at bug {{bug|61681}}. If only a subset, comment should be added to that report indicated which functions are covered by the patch/push.
<div style="column-count:2;-moz-column-count:2;-webkit-column-count:2">
* examples/code/@FIRfilter/FIRfilter.m
* examples/code/@FIRfilter/FIRfilter_aggregation.m
* examples/code/@polynomial/polynomial.m
* examples/code/@polynomial/polynomial_superiorto.m
* scripts/@ftp/cd.m
* scripts/audio/@audioplayer/set.m
* scripts/audio/@audiorecorder/set.m
* scripts/audio/record.m
* scripts/general/accumarray.m
* scripts/general/cplxpair.m
* scripts/general/dblquad.m
* scripts/general/flip.m
* scripts/general/interpft.m
* scripts/general/logspace.m
* scripts/general/num2str.m
* scripts/general/polyarea.m
* scripts/general/postpad.m
* scripts/general/prepad.m
* scripts/general/randi.m
* scripts/general/repmat.m
* scripts/general/rng.m
* scripts/general/rot90.m
* scripts/general/rotdim.m
* scripts/general/shift.m
* scripts/general/structfun.m
* scripts/general/triplequad.m
* scripts/geometry/voronoi.m
* scripts/gui/errordlg.m
* scripts/gui/helpdlg.m
* scripts/gui/uipanel.m
* scripts/gui/uipushtool.m
* scripts/gui/uitoggletool.m
* scripts/gui/uitoolbar.m
* scripts/gui/waitforbuttonpress.m
* scripts/gui/warndlg.m
* scripts/help/doc.m
* scripts/help/help.m
* scripts/help/lookfor.m
* scripts/help/type.m
* scripts/image/im2double.m
* scripts/image/im2frame.m
* scripts/image/image.m
* scripts/image/imagesc.m
* scripts/image/imformats.m
* scripts/image/imshow.m
* scripts/image/rgbplot.m
* scripts/java/javachk.m
* scripts/java/javaclasspath.m
* scripts/java/javamem.m
* scripts/legacy/@inline/inline.m
* scripts/legacy/findstr.m
* scripts/legacy/flipdim.m
* scripts/legacy/strmatch.m
* scripts/linear-algebra/cond.m
* scripts/linear-algebra/cross.m
* scripts/linear-algebra/isdefinite.m
* scripts/linear-algebra/ishermitian.m
* scripts/linear-algebra/issymmetric.m
* scripts/linear-algebra/orth.m
* scripts/linear-algebra/rank.m
* scripts/linear-algebra/rref.m
* scripts/miscellaneous/bunzip2.m
* scripts/miscellaneous/cast.m
* scripts/miscellaneous/computer.m
* scripts/miscellaneous/copyfile.m
* scripts/miscellaneous/dir.m
* scripts/miscellaneous/dos.m
* scripts/miscellaneous/edit.m
* scripts/miscellaneous/fileattrib.m
* scripts/miscellaneous/grabcode.m
* scripts/miscellaneous/gunzip.m
* scripts/miscellaneous/inputname.m
* scripts/miscellaneous/isfolder.m
* scripts/miscellaneous/ismethod.m
* scripts/miscellaneous/license.m
* scripts/miscellaneous/list_primes.m
* scripts/miscellaneous/ls.m
* scripts/miscellaneous/memory.m
* scripts/miscellaneous/methods.m
* scripts/miscellaneous/mex.m
* scripts/miscellaneous/mkdir.m
* scripts/miscellaneous/mkoctfile.m
* scripts/miscellaneous/movefile.m
* scripts/miscellaneous/nargoutchk.m
* scripts/miscellaneous/nthargout.m
* scripts/miscellaneous/open.m
* scripts/miscellaneous/publish.m
* scripts/miscellaneous/unix.m
* scripts/miscellaneous/untar.m
* scripts/miscellaneous/unzip.m
* scripts/miscellaneous/validateattributes.m
* scripts/miscellaneous/ver.m
* scripts/miscellaneous/what.m
* scripts/optimization/fminunc.m
* scripts/optimization/fsolve.m
* scripts/optimization/fzero.m
* scripts/optimization/optimget.m
* scripts/optimization/optimset.m
* scripts/path/import.m
* scripts/path/savepath.m
* scripts/pkg/pkg.m
* scripts/plot/appearance/annotation.m
* scripts/plot/appearance/axis.m
* scripts/plot/appearance/caxis.m
* scripts/plot/appearance/clabel.m
* scripts/plot/appearance/gtext.m
* scripts/plot/appearance/hidden.m
* scripts/plot/appearance/legend.m
* scripts/plot/appearance/material.m
* scripts/plot/appearance/orient.m
* scripts/plot/appearance/private/__gnuplot_legend__.m
* scripts/plot/appearance/specular.m
* scripts/plot/appearance/text.m
* scripts/plot/appearance/title.m
* scripts/plot/appearance/view.m
* scripts/plot/appearance/xlabel.m
* scripts/plot/appearance/ylabel.m
* scripts/plot/appearance/zlabel.m
* scripts/plot/draw/area.m
* scripts/plot/draw/bar.m
* scripts/plot/draw/barh.m
* scripts/plot/draw/camlight.m
* scripts/plot/draw/colorbar.m
* scripts/plot/draw/compass.m
* scripts/plot/draw/contour.m
* scripts/plot/draw/contour3.m
* scripts/plot/draw/contourf.m
* scripts/plot/draw/cylinder.m
* scripts/plot/draw/ellipsoid.m
* scripts/plot/draw/errorbar.m
* scripts/plot/draw/ezcontour.m
* scripts/plot/draw/ezcontourf.m
* scripts/plot/draw/ezmesh.m
* scripts/plot/draw/ezmeshc.m
* scripts/plot/draw/ezplot.m
* scripts/plot/draw/ezplot3.m
* scripts/plot/draw/ezpolar.m
* scripts/plot/draw/ezsurf.m
* scripts/plot/draw/ezsurfc.m
* scripts/plot/draw/feather.m
* scripts/plot/draw/fill.m
* scripts/plot/draw/fill3.m
* scripts/plot/draw/fplot.m
* scripts/plot/draw/hist.m
* scripts/plot/draw/light.m
* scripts/plot/draw/lightangle.m
* scripts/plot/draw/line.m
* scripts/plot/draw/loglog.m
* scripts/plot/draw/loglogerr.m
* scripts/plot/draw/mesh.m
* scripts/plot/draw/meshc.m
* scripts/plot/draw/meshz.m
* scripts/plot/draw/ostreamtube.m
* scripts/plot/draw/pareto.m
* scripts/plot/draw/patch.m
* scripts/plot/draw/pcolor.m
* scripts/plot/draw/peaks.m
* scripts/plot/draw/pie.m
* scripts/plot/draw/pie3.m
* scripts/plot/draw/plot.m
* scripts/plot/draw/plot3.m
* scripts/plot/draw/plotmatrix.m
* scripts/plot/draw/plotyy.m
* scripts/plot/draw/polar.m
* scripts/plot/draw/quiver.m
* scripts/plot/draw/quiver3.m
* scripts/plot/draw/rectangle.m
* scripts/plot/draw/ribbon.m
* scripts/plot/draw/rose.m
* scripts/plot/draw/scatter.m
* scripts/plot/draw/scatter3.m
* scripts/plot/draw/semilogx.m
* scripts/plot/draw/semilogxerr.m
* scripts/plot/draw/semilogy.m
* scripts/plot/draw/semilogyerr.m
* scripts/plot/draw/shrinkfaces.m
* scripts/plot/draw/slice.m
* scripts/plot/draw/sombrero.m
* scripts/plot/draw/sphere.m
* scripts/plot/draw/stairs.m
* scripts/plot/draw/stem.m
* scripts/plot/draw/stem3.m
* scripts/plot/draw/stemleaf.m
* scripts/plot/draw/streamline.m
* scripts/plot/draw/streamribbon.m
* scripts/plot/draw/streamtube.m
* scripts/plot/draw/surf.m
* scripts/plot/draw/surface.m
* scripts/plot/draw/surfc.m
* scripts/plot/draw/surfl.m
* scripts/plot/draw/surfnorm.m
* scripts/plot/draw/tetramesh.m
* scripts/plot/draw/trimesh.m
* scripts/plot/draw/triplot.m
* scripts/plot/draw/trisurf.m
* scripts/plot/draw/waterfall.m
* scripts/plot/util/axes.m
* scripts/plot/util/clf.m
* scripts/plot/util/close.m
* scripts/plot/util/figure.m
* scripts/plot/util/hggroup.m
* scripts/plot/util/isgraphics.m
* scripts/plot/util/ishold.m
* scripts/plot/util/newplot.m
* scripts/plot/util/openfig.m
* scripts/plot/util/pan.m
* scripts/plot/util/print.m
* scripts/plot/util/printd.m
* scripts/plot/util/rotate3d.m
* scripts/plot/util/subplot.m
* scripts/plot/util/zoom.m
* scripts/plot/util/__actual_axis_position__.m
* scripts/plot/util/__opengl_info__.m
* scripts/polynomial/conv.m
* scripts/polynomial/poly.m
* scripts/polynomial/polyder.m
* scripts/polynomial/polyint.m
* scripts/polynomial/polyout.m
* scripts/prefs/ispref.m
* scripts/prefs/prefdir.m
* scripts/profiler/profile.m
* scripts/set/powerset.m
* scripts/set/unique.m
* scripts/signal/blackman.m
* scripts/signal/fftconv.m
* scripts/signal/fftfilt.m
* scripts/signal/fftshift.m
* scripts/signal/hamming.m
* scripts/signal/hanning.m
* scripts/signal/ifftshift.m
* scripts/signal/spectral_adf.m
* scripts/signal/spectral_xdf.m
* scripts/sparse/gplot.m
* scripts/sparse/ilu.m
* scripts/sparse/private/__sprand__.m
* scripts/sparse/sprand.m
* scripts/sparse/sprandn.m
* scripts/sparse/sprandsym.m
* scripts/sparse/treelayout.m
* scripts/specfun/betainc.m
* scripts/specfun/betaincinv.m
* scripts/specfun/gammainc.m
* scripts/specfun/gammaincinv.m
* scripts/specfun/lcm.m
* scripts/specfun/pow2.m
* scripts/special-matrix/gallery.m
* scripts/special-matrix/hankel.m
* scripts/special-matrix/pascal.m
* scripts/special-matrix/toeplitz.m
* scripts/special-matrix/vander.m
* scripts/statistics/center.m
* scripts/statistics/corr.m
* scripts/statistics/cov.m
* scripts/statistics/discrete_rnd.m
* scripts/statistics/empirical_rnd.m
* scripts/statistics/kendall.m
* scripts/statistics/kurtosis.m
* scripts/statistics/mad.m
* scripts/statistics/mean.m
* scripts/statistics/meansq.m
* scripts/statistics/median.m
* scripts/statistics/mode.m
* scripts/statistics/moment.m
* scripts/statistics/range.m
* scripts/statistics/ranks.m
* scripts/statistics/run_count.m
* scripts/statistics/skewness.m
* scripts/statistics/spearman.m
* scripts/statistics/statistics.m
* scripts/statistics/std.m
* scripts/statistics/var.m
* scripts/strings/dec2base.m
* scripts/strings/dec2bin.m
* scripts/strings/dec2hex.m
* scripts/strings/index.m
* scripts/strings/strjust.m
* scripts/strings/substr.m
* scripts/strings/untabify.m
* scripts/testfun/assert.m
* scripts/testfun/example.m
* scripts/testfun/fail.m
* scripts/testfun/speed.m
* scripts/testfun/test.m
* scripts/testfun/__run_test_suite__.m
* scripts/time/is_leap_year.m
</div>
[[Category:Project Ideas]]
Retrieved from "https://wiki.octave.org/Special:MobileDiff/12894...14084"

Navigation menu