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

41
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
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
----------------------
@ -186,21 +201,25 @@ file.
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
in your source code the hyper link *See source* will appear pointing to the
implementation of that item on a GitHub repository. You can click the link to
see the implementation of the item.
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.
If you want to reuse this feature in your own documentation you will have to
modify ``config/nimdoc.cfg`` to contain a ``doc.item.seesrc`` value with a
hyper link to your own code repository. As you will see by the comments in that
file, the value ``txt`` passed on the command line will be used in the HTML
template along others like ``$path`` and ``$line``.
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.
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
``tools/nimweb.nim`` helper queries the current git commit hash during doc
generation, but since you might be working on an unpublished repository, it

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
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)*``
means 0 or more ``a``'s, ``a+`` means 1 or more ``a``'s, and ``(a)?`` means an