mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-04-19 05:50:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

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
parent 8d206b20d4
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
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
@@ -231,7 +250,7 @@ HTML anchor generation
======================
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
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
@@ -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
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,
you will need to use the complex name. A complex name for a callable type is
made up from several parts:
@@ -313,14 +332,14 @@ columns is:
1. Mandatory term being indexed. Terms can include quoting according to
Nim's rules (eg. \`^\`).
2. Base filename plus anchor hyper link (eg.
2. Base filename plus anchor hyperlink (eg.
``algorithm.html#*,int,SortOrder``).
3. Optional human readable string to display as hyper link. If the value is not
present or is the empty string, the hyper link will be rendered
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 hyper link. Browsers usually display
this as a tooltip after hovering a moment over the hyper link.
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

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