<commit_before>IDLdoc 3.3 Tutorial
===================

:Author: <NAME>

:Abstract: This tutorial attempts to provide a friendly guide to start using IDLdoc. See the companion reference guide for a more detailed listing of all the options that IDLdoc provides.


Introduction
------------

IDLdoc generates nicely formatted API documentation directly from source code. If the documentation is close to the code it is much more likely to be kept up-to-date. As much as possible is generated directly from the source code itself.

IDLdoc goals are to:

  #. provide browsable API documentation for both developers and users of the code base
  #. indicate portions of the API that are not documented
  #. analyze code for aspects like complexity

There are similar tools for other languages, notably:

  #. Javadoc for Java
  #. Doxygen for multiple Languages
  #. Sphinx for Python

IDLdoc can easily do code introspection because it is written in IDL.

The rst format and markup styles are inspired by the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ and `Markdown <http://daringfireball.net/projects/markdown/>`_ projects, though the syntax is not exactly the same as either one.

This tutorial intends to get a new user up to speed in using IDLdoc in the simplest way using the newer, more modern style of IDLdoc commenting. Don't worry, though, IDLdoc still supports legacy commenting styles so you don't have to go changing existing documentation (unless you want to make use of some of the cool, new features!). Experienced users will probably learn some new things too, since documentation for IDLdoc has been spotty in the past.


Installation
-------------------

To install IDLdoc, simply unzip and place the IDLdoc `.sav` file, or the `src/` directory if you are installing the IDLdoc source distribution, in your IDL path.

Do not separate the contents of the distribution; the code looks for files in locations relative to itself.


Basics
------

The basic calling sequence for IDLdoc specifies the path to a directory (or hierarchy of directories) with the `ROOT` keyword and, optionally, the path to where the output should be created::

    IDL> idldoc, root='path/to/code', output='path/to/output'

If `OUTPUT` is not specified, output will be created inside the `ROOT` hierarchy next to the source files. By default, IDLdoc creates HTML documentation, though it can be customized to create other types of documentation. To view the documentation produced from the above command, open `path/to/output/index.html` in a web browser.

IDLdoc will generate useful documentation from any valid IDL code, showing the calling sequence of routines even if there are no comments, or no comments in a format that IDLdoc recognizes, in the source code. But for more useful documentation, comments formatted in a simple manner that IDLdoc recognizes can be parsed and placed into the output documentation.

IDLdoc examines files with `.pro`, `.sav`, `.dlm`, and `.idldoc` extensions. Source code and specially formatted comments in `.pro` files are parsed. Save files, of either the code or data varieties, are examined for their contents and listing of the routines or variables contained are produced. DLM files produce a similar, but more limited, output as normal source code files. Finally, `.idldoc` files are a way of including documentation that is common to several items, such as an overview of a directory or a page describing a topic that several routines refer to.

Two keywords you most likely will want to specify are `TITLE` and `SUBTITLE`. Set these to string values to be displayed prominently on your documentation. For example, the command used to generate the API documentation for the IDLdoc project itself is::

   idldoc, root='src', output='api-docs', $
           title='API documentation for IDLdoc ' + idldoc_version(), $
           subtitle='IDLdoc ' + idldoc_version(/full), /statistics, $
           index_level=1, overview='overview', footer='footer', /embed, $
           format_style='rst', markup_style='rst'

This places the IDLdoc version information into the title/subtitle of the documentation. We'll talk about some of the other options in the following sections.

Note: By default, IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your `!PATH` can cause IDL to choose the (possibly outdated) copy in the doc output directory over the correct source file. It is recommended to either place your docs outside your `!PATH` or use the `NOSOURCE` keyword.


Comment format
--------------

TODO: difference between format and markup, `FORMAT_STYLE` and `MARKUP_STYLE` keywords; format styles = idldoc (the default), rst, idl, verbatim; markup styles = verbatim (the default, unless rst format style), rst (default for rst format style), preformatted

TODO: "rst" is the modern supported style for both format and markup in current versions of IDLdoc (although not the default); legacy format/markup is described in the reference manual.

The format style defines the format for comments within specially marked comment headers. Comment blocks which start with `;+` and end with `;-` are considered by IDLdoc::

  ;+
  ; This is a comment block.
  ;-

These comments start with a general description of the file or routine they are documenting, but the format styles define a format for adding comments about particular aspects such as individual parameters/keywords of a routine or author of a file.

There are three format styles allowed in IDLdoc comments: "rst", "IDLdoc", and "IDL." The "IDLdoc" and "IDL" format styles are for provided for legacy documentation headers; new comments should be written in the "rst" format style.<commit_msg>Adding to the tutorial.<commit_after>IDLdoc 3.3 Tutorial
===================

:Author: <NAME>

:Abstract: This tutorial attempts to provide a friendly guide to start using IDLdoc. See the companion reference guide for a more detailed listing of all the options that IDLdoc provides.


Introduction
------------

IDLdoc generates nicely formatted API documentation directly from source code. If the documentation is close to the code it is much more likely to be kept up-to-date. As much as possible is generated directly from the source code itself.

IDLdoc goals are to:

  #. provide browsable API documentation for both developers and users of the code base
  #. indicate portions of the API that are not documented
  #. analyze code for aspects like complexity

There are similar tools for other languages, notably:

  #. Javadoc for Java
  #. Doxygen for multiple Languages
  #. Sphinx for Python

IDLdoc can easily do code introspection because it is written in IDL.

The rst format and markup styles are inspired by the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ and `Markdown <http://daringfireball.net/projects/markdown/>`_ projects, though the syntax is not exactly the same as either one.

This tutorial intends to get a new user up to speed in using IDLdoc in the simplest way using the newer, more modern style of IDLdoc commenting. Don't worry, though, IDLdoc still supports legacy commenting styles so you don't have to go changing existing documentation (unless you want to make use of some of the cool, new features!). Experienced users will probably learn some new things too, since documentation for IDLdoc has been spotty in the past.


Installation
-------------------

To install IDLdoc, simply unzip and place the IDLdoc `.sav` file, or the `src/` directory if you are installing the IDLdoc source distribution, in your IDL path.

Do not separate the contents of the distribution; the code looks for files in locations relative to itself.


Basics
------

The basic calling sequence for IDLdoc specifies the path to a directory (or hierarchy of directories) with the `ROOT` keyword and, optionally, the path to where the output should be created::

    IDL> idldoc, root='path/to/code', output='path/to/output'

If `OUTPUT` is not specified, output will be created inside the `ROOT` hierarchy next to the source files. By default, IDLdoc creates HTML documentation, though it can be customized to create other types of documentation. To view the documentation produced from the above command, open `path/to/output/index.html` in a web browser.

IDLdoc will generate useful documentation from any valid IDL code, showing the calling sequence of routines even if there are no comments, or no comments in a format that IDLdoc recognizes, in the source code. But for more useful documentation, comments formatted in a simple manner that IDLdoc recognizes can be parsed and placed into the output documentation.

IDLdoc examines files with `.pro`, `.sav`, `.dlm`, and `.idldoc` extensions. Source code and specially formatted comments in `.pro` files are parsed. Save files, of either the code or data varieties, are examined for their contents and listing of the routines or variables contained are produced. DLM files produce a similar, but more limited, output as normal source code files. Finally, `.idldoc` files are a way of including documentation that is common to several items, such as an overview of a directory or a page describing a topic that several routines refer to.

Two keywords you most likely will want to specify are `TITLE` and `SUBTITLE`. Set these to string values to be displayed prominently on your documentation. For example, the command used to generate the API documentation for the IDLdoc project itself is::

   idldoc, root='src', output='api-docs', $
           title='API documentation for IDLdoc ' + idldoc_version(), $
           subtitle='IDLdoc ' + idldoc_version(/full), /statistics, $
           index_level=1, overview='overview', footer='footer', /embed, $
           format_style='rst', markup_style='rst'

This places the IDLdoc version information into the title/subtitle of the documentation. We'll talk about some of the other options in the following sections.

Note: By default, IDLdoc 3.0 copies source code into the output directory, so placing the output directory in your `!PATH` can cause IDL to choose the (possibly outdated) copy in the doc output directory over the correct source file. It is recommended to either place your docs outside your `!PATH` or use the `NOSOURCE` keyword.


Comment format
--------------

IDLdoc parses comment headers which start with ``;+`` and end with ``;``, like::

  ;+
  ; This is a comment header.
  ;-

If this comment header is immediately before or after a routine declaration header, then the comment is considered a routine-level comment and associated with the routine in the documentation. If not, then it is considered a file-level comment and associated with the file. For example, some file-level and routine-level comments are shown below::

  ;+
  ; File-level comments
  ;-

  ;+
  ; Routine-level comments
  ;-
  pro my_routine1
  ...
  end
  
  pro my_routine2
  ;+
  ; Routine-level comments
  ;-
  ...
  end
  
The comments inside the comment headers can just be free-form comments describing the routine, but they can also use various tags recognized by IDLdoc to document a particular aspect of the routine or file. For example, there is a `Keywords` tag allowing specifics about the keywords to be documented. 

A typical comment header for a routine is shown below::

  ;+
  ; Get an RGB color value for the specified color name. The available colors
  ; are:
  ;
  ; .. image:: vis_colors.png
  ;
  ; :Examples:
  ;    For example::
  ;
  ;       IDL> print, vis_color('black')
  ;          0   0   0
  ;       IDL> print, vis_color('slateblue')
  ;        106  90 205
  ;       IDL> c = vis_color('slateblue', /index) 
  ;       IDL> print, c, c, format='(I, Z)'
  ;           13458026      CD5A6A
  ;       IDL> print, vis_color(['blue', 'red', 'yellow'])
  ;          0 255 255
  ;          0   0 255
  ;        255   0   0
  ;       IDL> print, vis_color(/names)
  ;       aliceblue antiquewhite aqua aquamarine azure beige ...
  ;
  ;    These commands are in the main-level example program::
  ;
  ;       IDL> .run vis_color
  ;
  ; :Uses:
  ;    vis_src_root, vis_index2rgb
  ;
  ; :Returns:
  ;    Returns a triple as a bytarr(3) or bytarr(3, n) by default if a single
  ;    color name or n color names are given. Returns a decomposed color index 
  ;    as a long or lonarr(n) if `INDEX` keyword is set.
  ; 
  ;    Returns a string array for the names if `NAMES` keyword is set.
  ;
  ; :Params:
  ;    colorname : in, required, type=string/strarr
  ;       case-insensitive name(s) of the color; note that both "grey" and 
  ;       "gray" are accepted in all names that incorporate them
  ;
  ; :Keywords:
  ;    names : in, optional, type=boolean
  ;       set to return a string of color names
  ;    index : in, optional, type=boolean
  ;       set to return a long integer with the RGB decomposed into it
  ;    xkcd : in, optional, type=boolean
  ;       set to use xkcd color survey color names instead of the HTML color
  ;       names (see `xkcd color survey <http://xkcd.com/color/rgb/>`)
  ;-
  function vis_color, colorname, names=names, index=index, xkcd=xkcd


TODO: There are multiple formats for comments to make them understandable by IDLdoc, i.e., format styles. difference between format and markup, `FORMAT_STYLE` and `MARKUP_STYLE` keywords; format styles = idldoc (the default), rst, idl, verbatim; markup styles = verbatim (the default, unless rst format style), rst (default for rst format style), preformatted

There are three format styles allowed in IDLdoc comments: "rst", "IDLdoc", and "IDL." The "IDLdoc" and "IDL" format styles are for provided for legacy documentation headers; new comments should be written in the "rst" format style.

The "rst" format and markup styles are the modern supported style in current versions of IDLdoc (although the "IDLdoc" format style and the "verbatim" markup styles are the defaults). Legacy format and markup styles are described in the reference manual.
{'fraction_non_alphanumeric': 0.07061925461412386, 'fraction_numerical': 0.0037768118007553623, 'mean_word_length': 3.7686034658511725, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '84419', 'n_tokens_mistral': 3751, 'n_tokens_neox': 3552, 'n_words': 1972}