diff options
Diffstat (limited to 'doc/docgen.rst')
| -rw-r--r-- | doc/docgen.rst | 395 |
1 files changed, 0 insertions, 395 deletions
diff --git a/doc/docgen.rst b/doc/docgen.rst deleted file mode 100644 index dac8808ad..000000000 --- a/doc/docgen.rst +++ /dev/null @@ -1,395 +0,0 @@ -=================================== - Nim DocGen Tools Guide -=================================== - -:Author: Erik O'Leary -:Version: |nimversion| - -.. contents:: - - -Introduction -============ - -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 module -dependencies (``import``), any top-level documentation comments (##), and -exported symbols (*), including procedures, types, and variables. - -Quick start ------------ - -Generate HTML documentation for a file: - -:: - nim doc <filename>.nim - -Generate HTML documentation for a whole project: - -:: - # 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` - # See also `--docroot` to specify a relative root. - # to get search (dochacks.js) to work locally, you need a server otherwise - # 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. - - -Documentation Comments ----------------------- - -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 -documentation with only their well-documented code. - -Example: - -.. code-block:: nim - type Person* = object - ## This type contains a description of a person - name: string - age: int - -Outputs:: - Person* = object - name: string - age: int - -This type contains a description of a person - -Field documentation comments can be added to fields like so: - -.. code-block:: nim - var numValues: int ## \ - ## `numValues` stores the number of values - -Note that without the `*` following the name of the type, the documentation for -this type would not be generated. Documentation will only be generated for -*exported* types/procedures/etc. - - -Nim file input ------------------ - -The following examples will generate documentation for the below contrived -*Nim* module, aptly named 'sample.nim' - -sample.nim: - -.. code-block:: nim - ## This module is a sample. - - import strutils - - proc helloWorld*(times: int) = - ## Takes an integer and outputs - ## as many "hello world!"s - - for i in 0 .. times-1: - echo "hello world!" - - helloWorld(5) - - -Document Types -============== - - -HTML ----- - -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, -optionally, an index file. - -The ``doc`` command:: - nim doc sample - -Partial Output:: - ... - proc helloWorld(times: int) {.raises: [], tags: [].} - ... - -The full output can be seen here: `docgen_sample.html <docgen_sample.html>`_. -It runs after semantic checking, and includes pragmas attached implicitly by the -compiler. - - -JSON ----- - -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 ``jsondoc`` command:: - nim jsondoc sample - -Output:: - { - "orig": "docgen_sample.nim", - "nimble": "", - "moduleDescription": "This module is a sample", - "entries": [ - { - "name": "helloWorld", - "type": "skProc", - "line": 5, - "col": 0, - "description": "Takes an integer and outputs as many "hello world!"s", - "code": "proc helloWorld(times: int) {.raises: [], tags: [].}" - } - ] - } - -Similarly to the old ``doc`` command the old ``jsondoc`` command has been -renamed ``jsondoc0``. - -The ``jsondoc0`` command:: - nim jsondoc0 sample - -Output:: - [ - { - "comment": "This module is a sample." - }, - { - "name": "helloWorld", - "type": "skProc", - "description": "Takes an integer and outputs as many "hello world!"s", - "code": "proc helloWorld*(times: int)" - } - ] - -Note that the ``jsondoc`` command outputs it's JSON without pretty-printing it, -while ``jsondoc0`` outputs pretty-printed JSON. - -Related Options -=============== - -Project switch --------------- - -:: - 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`` -belongs to. - - -Index switch ------------- - -:: - nim doc2 --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 -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. - -Once index files have been generated for one or more modules, the Nim -compiler command ``buildIndex directory`` can be run to go over all the index -files in the specified directory to generate a `theindex.html <theindex.html>`_ -file. - -See source switch ------------------ - -The ``docSeeSrcUrl`` switch is deprecated. Use: - -:: - nim doc2 --git.url:<url> filename.nim - -With the ``git.url`` 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. - -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`. - -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. - -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 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 -specific commit in the output. - - -Other Input Formats -=================== - -The *Nim compiler* also has support for RST (reStructuredText) files with -the ``rst2html`` and ``rst2tex`` 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 -supports highlighting of C++ and some other c-like languages. - -Usage:: - nim rst2html docgen.txt - -Output:: - You're reading it! - -The ``rst2tex`` command is invoked identically to ``rst2html``, but outputs -a .tex file instead of .html. - - -HTML anchor generation -====================== - -When you run the ``rst2html`` 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`` or ``doc2`` -commands 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. - -The numerical identifier is just a random number. The number gets assigned -according to the section and position of the symbol in the file being processed -and you should not rely on it being constant: if you add or remove a symbol the -numbers may shuffle around. - -The plain name of a symbol is a simplified version of its fully exported -signature. Variables or constants have the same plain name symbol as their -complex name. The plain name for procs, templates, and other callable types -will be their unquoted value after removing parameters, return types and -pragmas. The plain name allows short and nice linking of symbols which works -unless you have a module with collisions due to overloading. - -If you hyperlink a plain name symbol and there are other matches on the same -HTML file, most browsers will go to the first one. To differentiate the rest, -you will need to use the complex name. A complex name for a callable type is -made up from several parts: - - (**plain symbol**)(**.type**),(**first param**)?(**,param type**)\* - -The first thing to note is that all callable types have at least a comma, even -if they don't have any parameters. If there are parameters, they are -represented by their types and will be comma separated. To the plain symbol a -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`` -------------- -------------- - -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 -symbols in the `system module <system.html>`_. - -* ``type SomeSignedInt = int | int8 | int16 | int32 | int64`` **=>** - `#SomeSignedInt <system.html#SomeSignedInt>`_ -* ``var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}`` **=>** - `#globalRaiseHook <system.html#globalRaiseHook>`_ -* ``const NimVersion = "0.0.0"`` **=>** - `#NimVersion <system.html#NimVersion>`_ -* ``proc getTotalMem(): int {.rtl, raises: [], tags: [].}`` **=>** - `#getTotalMem, <system.html#getTotalMem>`_ -* ``proc len[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}`` **=>** - `#len,seq[T] <system.html#len,seq[T]>`_ -* ``iterator pairs[T](a: seq[T]): tuple[key: int, val: T] {.inline.}`` **=>** - `#pairs.i,seq[T] <system.html#pairs.i,seq[T]>`_ -* ``template newException[](exceptn: typedesc; message: string; - parentException: ref Exception = nil): untyped`` **=>** - `#newException.t,typedesc,string,ref.Exception - <system.html#newException.t,typedesc,string,ref.Exception>`_ - - -Index (idx) file format -======================= - -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() -<rstgen.html#setIndexTerm,RstGenerator,string,string,string,string,string>`_ -and `writeIndexFile() <rstgen.html#writeIndexFile,RstGenerator,string>`_ procs. -The purpose of ``idx`` files is to hold the interesting symbols and their HTML -references so they can be later concatenated into a big index file with -`mergeIndexes() <rstgen.html#mergeIndexes,string>`_. This section documents -the file format in detail. - -Index files are line oriented and tab separated (newline and tab characters -have to be escaped). Each line represents a record with at least two fields, -but can have up to four (additional columns are ignored). The content of these -columns is: - -1. Mandatory term being indexed. Terms can include quoting according to - Nim's rules (eg. \`^\`). -2. Base filename plus anchor hyperlink (eg. - ``algorithm.html#*,int,SortOrder``). -3. Optional human readable string to display as 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 - not for an API symbol but for a TOC entry. -4. Optional title or description of the hyperlink. Browsers usually display - 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 -consist mainly of API entries. The latter are generic documents meant for -human reading. - -To differentiate both types (documents and APIs), the index generator will add -to the index of documents an entry with the title of the document. Since the -title is the topmost element, it will be added with a second field containing -just the filename without any HTML anchor. By convention this entry without -anchor is the *title entry*, and since entries in the index file are added as -they are scanned, the title entry will be the first line. The title for APIs -is not present because it can be generated concatenating the name of the file -to the word **Module**. - -Normal symbols are added to the index with surrounding whitespaces removed. An -exception to this are table of content (TOC) entries. TOC entries are added to -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. - - -Additional resources -==================== - -`Nim Compiler User Guide <nimc.html#compiler-usage-command-line-switches>`_ - -`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 -files to your project to change the look of docgen output. - -You can import the `packages/docutils/rstgen module <rstgen.html>`_ in your -programs if you want to reuse the compiler's documentation generation procs. |