Update docs around docSeeSrcUrl #6071 (#11074)

Flag docSeeSrcUrl as deprecated.
Add quick start paragraph.
Add links from the language manual.

2 files changed, 41 insertions, 19 deletions

diff --git a/doc/docgen.rst b/doc/docgen.rst
index 84969d8ee..bd7f9bf10 100644
--- a/doc/docgen.rst
+++ b/doc/docgen.rst
@@ -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
+
+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.
 
-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.
+Source URLs are generated as `href="${url}/tree/${commit}/${path}#L${line}"` by default and this compatible with GitHub but not with GitLab.
 
-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``.
+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 ``txt`` value is just a commit
+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
diff --git a/doc/manual.rst b/doc/manual.rst
index d2b35d36d..d4d2aae91 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -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