jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update docs around docSeeSrcUrl #6071 (#11074)

Browse source 
Flag docSeeSrcUrl as deprecated.
Add quick start paragraph.
Add links from the language manual.
This commit is contained in:
Federico Ceratto 2019-04-23 10:36:16 +01:00 • committed by Andreas Rumpf
commit 2cdff617fd
2 changed files with 41 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

55
doc/docgen.rst
View file

@ -18,6 +18,21 @@ from input .nim files and projects, as well as HTML and LaTeX from input RST
dependencies (``import``), any top-level documentation comments (##), and dependencies (``import``), any top-level documentation comments (##), and
exported symbols (*), including procedures, types, and variables. 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> <main_filename>.nim
nim buildIndex -o:htmldocs/theindex.html htmldocs
Documentation Comments Documentation Comments
---------------------- ----------------------
@ -186,21 +201,25 @@ file.
See source switch See source switch
----------------- -----------------
The ``docSeeSrcUrl`` switch is deprecated. Use:
:: ::
nim doc2 --docSeeSrcUrl:txt filename.nim nim doc2 --git.url:<url> filename.nim
When you pass the ``docSeeSrcUrl`` switch to docgen, after each documented item With the ``git.url`` switch the *See source* hyperlink will appear below each
in your source code the hyper link *See source* will appear pointing to the documented item in your source code pointing to the implementation of that
implementation of that item on a GitHub repository. You can click the link to item on a GitHub repository.
see the implementation of the item. You can click the link to see the implementation of the item.
If you want to reuse this feature in your own documentation you will have to The ``git.commit`` switch overrides the hardcoded `devel` branch in config/nimdoc.cfg.
modify ``config/nimdoc.cfg`` to contain a ``doc.item.seesrc`` value with a This is useful to link to a different branch e.g. `--git.commit:master`,
hyper link to your own code repository. As you will see by the comments in that or to a tag e.g. `--git.commit:1.2.3` or a commit.
file, the value ``txt`` passed on the command line will be used in the HTML
template along others like ``$path`` and ``$line``.
In the case of Nim's own documentation, the ``txt`` value is just 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.
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/Araq/Nim. The hash to append to a formatted URL to https://github.com/Araq/Nim. The
``tools/nimweb.nim`` helper queries the current git commit hash during doc ``tools/nimweb.nim`` helper queries the current git commit hash during doc
generation, but since you might be working on an unpublished repository, it generation, but since you might be working on an unpublished repository, it
@ -231,7 +250,7 @@ HTML anchor generation
====================== ======================
When you run the ``rst2html`` command, all sections in the RST document will When you run the ``rst2html`` command, all sections in the RST document will
get an anchor you can hyper link to. Usually you can guess the anchor lower 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 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`` 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 commands to generate API documentation, some symbol get one or two anchors at
@ -249,7 +268,7 @@ will be their unquoted value after removing parameters, return types and
pragmas. The plain name allows short and nice linking of symbols which works pragmas. The plain name allows short and nice linking of symbols which works
unless you have a module with collisions due to overloading. unless you have a module with collisions due to overloading.
If you hyper link a plain name symbol and there are other matches on the same 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, 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 you will need to use the complex name. A complex name for a callable type is
made up from several parts: made up from several parts:
@ -313,14 +332,14 @@ columns is:
1. Mandatory term being indexed. Terms can include quoting according to 1. Mandatory term being indexed. Terms can include quoting according to
Nim's rules (eg. \`^\`). Nim's rules (eg. \`^\`).
2. Base filename plus anchor hyper link (eg. 2. Base filename plus anchor hyperlink (eg.
``algorithm.html#*,int,SortOrder``). ``algorithm.html#*,int,SortOrder``).
3. Optional human readable string to display as hyper link. If the value is not 3. Optional human readable string to display as hyperlink. If the value is not
present or is the empty string, the hyper link will be rendered present or is the empty string, the hyperlink will be rendered
using the term. Prefix whitespace indicates that this entry is using the term. Prefix whitespace indicates that this entry is
not for an API symbol but for a TOC entry. not for an API symbol but for a TOC entry.
4. Optional title or description of the hyper link. Browsers usually display 4. Optional title or description of the hyperlink. Browsers usually display
this as a tooltip after hovering a moment over the hyper link. this as a tooltip after hovering a moment over the hyperlink.
The index generation tools try to differentiate between documentation The index generation tools try to differentiate between documentation
generated from ``.nim`` files and documentation generated from ``.txt`` or generated from ``.nim`` files and documentation generated from ``.txt`` or

5
doc/manual.rst
View file

@ -22,7 +22,10 @@ precise wording. This manual is constantly evolving into a proper specification.
**Note**: The experimental features of Nim are **Note**: The experimental features of Nim are
covered `here <manual_experimental.html>`_. covered `here <manual_experimental.html>`_.
This document describes the lexis, the syntax, and the semantics of Nim. This document describes the lexis, the syntax, and the semantics of the Nim language.
To learn how to compile Nim programs and generate documentation see
`Compiler User Guide <nimc.html>`_ and `DocGen Tools Guide <docgen.html>`_.
The language constructs are explained using an extended BNF, in which ``(a)*`` The language constructs are explained using an extended BNF, in which ``(a)*``
means 0 or more ``a``'s, ``a+`` means 1 or more ``a``'s, and ``(a)?`` means an means 0 or more ``a``'s, ``a+`` means 1 or more ``a``'s, and ``(a)?`` means an