* follow-up #17837: add `Console` for interactive sessions * fix Latex
This commit is contained in:
Andrey Makarov
GitHub
parent
706562f661
commit
436af88d8c
14 changed files with 252 additions and 155 deletions
145
doc/docgen.rst
145
doc/docgen.rst
|
|
@ -1,5 +1,3 @@
|
|||
.. default-role:: code
|
||||
|
||||
===================================
|
||||
Nim DocGen Tools Guide
|
||||
===================================
|
||||
|
|
@ -7,6 +5,8 @@
|
|||
:Author: Erik O'Leary
|
||||
:Version: |nimversion|
|
||||
|
||||
.. include:: rstcommon.rst
|
||||
.. default-role:: Nim
|
||||
.. contents::
|
||||
|
||||
|
||||
|
|
@ -17,20 +17,22 @@ This document describes the `documentation generation tools`:idx: built into
|
|||
the `Nim compiler <nimc.html>`_, which can generate HTML and JSON output
|
||||
from input .nim files and projects, as well as HTML and LaTeX from input RST
|
||||
(reStructuredText) files. The output documentation will include the module
|
||||
dependencies (`import`), any top-level documentation comments (##), and
|
||||
exported symbols (*), including procedures, types, and variables.
|
||||
dependencies (`import`), any top-level documentation comments (`##`), and
|
||||
exported symbols (`*`), including procedures, types, and variables.
|
||||
|
||||
Quick start
|
||||
-----------
|
||||
|
||||
Generate HTML documentation for a file:
|
||||
|
||||
::
|
||||
.. code:: cmd
|
||||
|
||||
nim doc <filename>.nim
|
||||
|
||||
Generate HTML documentation for a whole project:
|
||||
|
||||
::
|
||||
.. code:: cmd
|
||||
|
||||
# delete any htmldocs/*.idx file before starting
|
||||
nim doc --project --index:on --git.url:<url> --git.commit:<tag> --outdir:htmldocs <main_filename>.nim
|
||||
# this will generate html files, a theindex.html index, css and js under `htmldocs`
|
||||
|
|
@ -39,15 +41,15 @@ Generate HTML documentation for a whole project:
|
|||
# CORS will prevent opening file:// urls; this works:
|
||||
python3 -m http.server 7029 --directory htmldocs
|
||||
# When --outdir is omitted it defaults to $projectPath/htmldocs,
|
||||
or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
|
||||
and likewise without `--project`.
|
||||
Adding `-r` will open in a browser directly.
|
||||
# or `$nimcache/htmldocs` with `--usenimcache` which avoids clobbering your sources;
|
||||
# and likewise without `--project`.
|
||||
# Adding `-r` will open in a browser directly.
|
||||
|
||||
|
||||
Documentation Comments
|
||||
----------------------
|
||||
|
||||
Any comments which are preceded by a double-hash (##), are interpreted as
|
||||
Any comments which are preceded by a double-hash (`##`), are interpreted as
|
||||
documentation. Comments are parsed as RST (see `reference
|
||||
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing
|
||||
Nim module authors the ability to easily generate richly formatted
|
||||
|
|
@ -66,7 +68,7 @@ Outputs::
|
|||
name: string
|
||||
age: int
|
||||
|
||||
This type contains a description of a person
|
||||
This type contains a description of a person
|
||||
|
||||
Field documentation comments can be added to fields like so:
|
||||
|
||||
|
|
@ -127,12 +129,15 @@ Document Types
|
|||
HTML
|
||||
----
|
||||
|
||||
The generation of HTML documents is done via the `doc` command. This command
|
||||
takes either a single .nim file, outputting a single .html file with the same
|
||||
base filename, or multiple .nim files, outputting multiple .html files and,
|
||||
The generation of HTML documents is done via the `doc`:option: command. This command
|
||||
takes either a single ``.nim`` file, outputting a single ``.html`` file with the same
|
||||
base filename, or multiple ``.nim`` files, outputting multiple ``.html`` files and,
|
||||
optionally, an index file.
|
||||
|
||||
The `doc` command::
|
||||
The `doc`:option: command:
|
||||
|
||||
.. code:: cmd
|
||||
|
||||
nim doc sample
|
||||
|
||||
Partial Output::
|
||||
|
|
@ -148,12 +153,16 @@ compiler.
|
|||
JSON
|
||||
----
|
||||
|
||||
The generation of JSON documents is done via the `jsondoc` command. This command
|
||||
takes in a .nim file and outputs a .json file with the same base filename. Note
|
||||
that this tool is built off of the `doc` command (previously `doc2`), and
|
||||
contains the same information.
|
||||
The generation of JSON documents is done via the `jsondoc`:option: command.
|
||||
This command takes in a ``.nim`` file and outputs a ``.json`` file with
|
||||
the same base filename.
|
||||
Note that this tool is built off of the `doc`:option: command
|
||||
(previously `doc2`:option:), and contains the same information.
|
||||
|
||||
The `jsondoc`:option: command:
|
||||
|
||||
.. code:: cmd
|
||||
|
||||
The `jsondoc` command::
|
||||
nim jsondoc sample
|
||||
|
||||
Output::
|
||||
|
|
@ -173,10 +182,13 @@ Output::
|
|||
]
|
||||
}
|
||||
|
||||
Similarly to the old `doc` command, the old `jsondoc` command has been
|
||||
renamed to `jsondoc0`.
|
||||
Similarly to the old `doc`:option: command, the old `jsondoc`:option: command has been
|
||||
renamed to `jsondoc0`:option:.
|
||||
|
||||
The `jsondoc0`:option: command:
|
||||
|
||||
.. code:: cmd
|
||||
|
||||
The `jsondoc0` command::
|
||||
nim jsondoc0 sample
|
||||
|
||||
Output::
|
||||
|
|
@ -192,8 +204,8 @@ Output::
|
|||
}
|
||||
]
|
||||
|
||||
Note that the `jsondoc` command outputs it's JSON without pretty-printing it,
|
||||
while `jsondoc0` outputs pretty-printed JSON.
|
||||
Note that the `jsondoc`:option: command outputs it's JSON without pretty-printing it,
|
||||
while `jsondoc0`:option: outputs pretty-printed JSON.
|
||||
|
||||
Related Options
|
||||
===============
|
||||
|
|
@ -201,22 +213,24 @@ Related Options
|
|||
Project switch
|
||||
--------------
|
||||
|
||||
::
|
||||
.. code:: cmd
|
||||
|
||||
nim doc --project filename.nim
|
||||
|
||||
This will recursively generate documentation of all nim modules imported
|
||||
into the input module that belong to the Nimble package that `filename.nim`
|
||||
into the input module that belong to the Nimble package that ``filename.nim``
|
||||
belongs to.
|
||||
|
||||
|
||||
Index switch
|
||||
------------
|
||||
|
||||
::
|
||||
.. code:: cmd
|
||||
|
||||
nim doc --index:on filename.nim
|
||||
|
||||
This will generate an index of all the exported symbols in the input Nim
|
||||
module, and put it into a neighboring file with the extension of `.idx`. The
|
||||
module, and put it into a neighboring file with the extension of ``.idx``. The
|
||||
index file is line-oriented (newlines have to be escaped). Each line
|
||||
represents a tab-separated record of several columns, the first two mandatory,
|
||||
the rest optional. See the `Index (idx) file format`_ section for details.
|
||||
|
|
@ -229,31 +243,37 @@ file.
|
|||
See source switch
|
||||
-----------------
|
||||
|
||||
::
|
||||
.. code:: cmd
|
||||
|
||||
nim doc --git.url:<url> filename.nim
|
||||
|
||||
With the `git.url` switch the *See source* hyperlink will appear below each
|
||||
With the `git.url`:option: switch the *See source* hyperlink will appear below each
|
||||
documented item in your source code pointing to the implementation of that
|
||||
item on a GitHub repository.
|
||||
You can click the link to see the implementation of the item.
|
||||
|
||||
The `git.commit` switch overrides the hardcoded `devel` branch in config/nimdoc.cfg.
|
||||
This is useful to link to a different branch e.g. `--git.commit:master`,
|
||||
or to a tag e.g. `--git.commit:1.2.3` or a commit.
|
||||
The `git.commit`:option: switch overrides the hardcoded `devel` branch in config/nimdoc.cfg.
|
||||
This is useful to link to a different branch e.g. `--git.commit:master`:option:,
|
||||
or to a tag e.g. `--git.commit:1.2.3`:option: or a commit.
|
||||
|
||||
Source URLs are generated as `href="${url}/tree/${commit}/${path}#L${line}"` by default and this compatible with GitHub but not with GitLab.
|
||||
Source URLs are generated as ``href="${url}/tree/${commit}/${path}#L${line}"``
|
||||
by default and this compatible with GitHub but not with GitLab.
|
||||
|
||||
Similarly, `git.devel` switch overrides the hardcoded `devel` branch for the `Edit` link which is also useful if you have a different working branch than `devel` e.g. `--git.devel:master`.
|
||||
Similarly, `git.devel`:option: switch overrides the hardcoded `devel` branch
|
||||
for the `Edit` link which is also useful if you have a different working
|
||||
branch than `devel` e.g. `--git.devel:master`:option:.
|
||||
|
||||
Edit URLs are generated as `href="${url}/tree/${devel}/${path}#L${line}"` by default.
|
||||
Edit URLs are generated as ``href="${url}/tree/${devel}/${path}#L${line}"``
|
||||
by default.
|
||||
|
||||
You can edit `config/nimdoc.cfg` and modify the `doc.item.seesrc` value with a hyperlink to your own code repository.
|
||||
You can edit ``config/nimdoc.cfg`` and modify the ``doc.item.seesrc`` value
|
||||
with a hyperlink to your own code repository.
|
||||
|
||||
In the case of Nim's own documentation, the `commit` value is just a commit
|
||||
hash to append to a formatted URL to https://github.com/nim-lang/Nim. The
|
||||
`tools/nimweb.nim` helper queries the current git commit hash during the doc
|
||||
``tools/nimweb.nim`` helper queries the current git commit hash during the doc
|
||||
generation, but since you might be working on an unpublished repository, it
|
||||
also allows specifying a `githash` value in `web/website.ini` to force a
|
||||
also allows specifying a `githash` value in ``web/website.ini`` to force a
|
||||
specific commit in the output.
|
||||
|
||||
|
||||
|
|
@ -261,28 +281,31 @@ Other Input Formats
|
|||
===================
|
||||
|
||||
The *Nim compiler* also has support for RST (reStructuredText) files with
|
||||
the `rst2html` and `rst2tex` commands. Documents like this one are
|
||||
the `rst2html`:option: and `rst2tex`:option: commands. Documents like this one are
|
||||
initially written in a dialect of RST which adds support for nim source code
|
||||
highlighting with the `.. code-block:: nim` prefix. `code-block` also
|
||||
highlighting with the ``.. code-block:: nim`` prefix. ``code-block`` also
|
||||
supports highlighting of C++ and some other c-like languages.
|
||||
|
||||
Usage::
|
||||
nim rst2html docgen.txt
|
||||
Usage:
|
||||
|
||||
.. code:: cmd
|
||||
|
||||
nim rst2html docgen.rst
|
||||
|
||||
Output::
|
||||
You're reading it!
|
||||
|
||||
The `rst2tex` command is invoked identically to `rst2html`, but outputs
|
||||
a .tex file instead of .html.
|
||||
The `rst2tex`:option: command is invoked identically to `rst2html`:option:,
|
||||
but outputs a ``.tex`` file instead of ``.html``.
|
||||
|
||||
|
||||
HTML anchor generation
|
||||
======================
|
||||
|
||||
When you run the `rst2html` command, all sections in the RST document will
|
||||
When you run the `rst2html`:option: command, all sections in the RST document will
|
||||
get an anchor you can hyperlink to. Usually, you can guess the anchor lower
|
||||
casing the section title and replacing spaces with dashes, and in any case, you
|
||||
can get it from the table of contents. But when you run the `doc`
|
||||
can get it from the table of contents. But when you run the `doc`:option:
|
||||
command to generate API documentation, some symbol get one or two anchors at
|
||||
the same time: a numerical identifier, or a plain name plus a complex name.
|
||||
|
||||
|
|
@ -314,15 +337,15 @@ suffix may be added depending on the type of the callable:
|
|||
Callable type Suffix
|
||||
------------- --------------
|
||||
proc *empty string*
|
||||
macro `.m`
|
||||
method `.e`
|
||||
iterator `.i`
|
||||
template `.t`
|
||||
converter `.c`
|
||||
macro ``.m``
|
||||
method ``.e``
|
||||
iterator ``.i``
|
||||
template ``.t``
|
||||
converter ``.c``
|
||||
------------- --------------
|
||||
|
||||
The relationship of type to suffix is made by the proc `complexName` in the
|
||||
`compiler/docgen.nim` file. Here are some examples of complex names for
|
||||
``compiler/docgen.nim`` file. Here are some examples of complex names for
|
||||
symbols in the `system module <system.html>`_.
|
||||
|
||||
* `type SomeSignedInt = int | int8 | int16 | int32 | int64` **=>**
|
||||
|
|
@ -346,7 +369,7 @@ symbols in the `system module <system.html>`_.
|
|||
Index (idx) file format
|
||||
=======================
|
||||
|
||||
Files with the `.idx` extension are generated when you use the `Index
|
||||
Files with the ``.idx`` extension are generated when you use the `Index
|
||||
switch <#related-options-index-switch>`_ along with commands to generate
|
||||
documentation from source or text files. You can programmatically generate
|
||||
indices with the `setIndexTerm()
|
||||
|
|
@ -364,7 +387,7 @@ columns is:
|
|||
|
||||
1. Mandatory term being indexed. Terms can include quoting according to
|
||||
Nim's rules (e.g. \`^\`).
|
||||
2. Base filename plus anchor hyperlink (e.g. `algorithm.html#*,int,SortOrder`).
|
||||
2. Base filename plus anchor hyperlink (e.g. ``algorithm.html#*,int,SortOrder``).
|
||||
3. Optional human-readable string to display as a hyperlink. If the value is not
|
||||
present or is the empty string, the hyperlink will be rendered
|
||||
using the term. Prefix whitespace indicates that this entry is
|
||||
|
|
@ -373,8 +396,8 @@ columns is:
|
|||
this as a tooltip after hovering a moment over the hyperlink.
|
||||
|
||||
The index generation tools try to differentiate between documentation
|
||||
generated from `.nim` files and documentation generated from `.txt` or
|
||||
`.rst` files. The former are always closely related to source code and
|
||||
generated from ``.nim`` files and documentation generated from ``.txt`` or
|
||||
``.rst`` files. The former are always closely related to source code and
|
||||
consist mainly of API entries. The latter are generic documents meant for
|
||||
human reading.
|
||||
|
||||
|
|
@ -393,7 +416,7 @@ the index file with their third column having as much prefix spaces as their
|
|||
level is in the TOC (at least 1 character). The prefix whitespace helps to
|
||||
filter TOC entries from API or text symbols. This is important because the
|
||||
amount of spaces is used to replicate the hierarchy for document TOCs in the
|
||||
final index, and TOC entries found in `.nim` files are discarded.
|
||||
final index, and TOC entries found in ``.nim`` files are discarded.
|
||||
|
||||
|
||||
Additional resources
|
||||
|
|
@ -404,8 +427,8 @@ Additional resources
|
|||
`RST Quick Reference
|
||||
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
|
||||
|
||||
The output for HTML and LaTeX comes from the `config/nimdoc.cfg` and
|
||||
`config/nimdoc.tex.cfg` configuration files. You can add and modify these
|
||||
The output for HTML and LaTeX comes from the ``config/nimdoc.cfg`` and
|
||||
``config/nimdoc.tex.cfg`` configuration files. You can add and modify these
|
||||
files to your project to change the look of the docgen output.
|
||||
|
||||
You can import the `packages/docutils/rstgen module <rstgen.html>`_ in your
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue