Skip to content

Commit

Permalink
Markdown links migration part 1 (#20319)
Browse files Browse the repository at this point in the history 
Markdown link migration part 1

Also the warning is improved a bit.

Local links (targeting inside its document) which had had a full anchor
were turned into concise form.
The very fact that they existed may be due to the bug in
reference to subsections fixed #20279,
now they are working well (both in RST syntax and
new Pandoc Markdown syntax implemented in
#20304)
  • Loading branch information
@a-mr
a-mr authored Sep 9, 2022
1 parent 89e6540 commit f6ee066
Show file tree
Hide file tree
Showing 12 changed files with 256 additions and 240 deletions.
81 changes: 41 additions & 40 deletions doc/backends.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
Introduction
============

The `Nim Compiler User Guide <nimc.html>`_ documents the typical
The [Nim Compiler User Guide](nimc.html) documents the typical
compiler invocation, using the `compile`:option:
or `c`:option: command to transform a
``.nim`` file into one or more ``.c`` files which are then compiled with the
Expand All @@ -26,12 +26,12 @@ to compile to C++, Objective-C, or JavaScript. This document tries to
concentrate in a single place all the backend and interfacing options.

The Nim compiler supports mainly two backend families: the C, C++ and
Objective-C targets and the JavaScript target. `The C like targets
<#backends-the-c-like-targets>`_ creates source files that can be compiled
into a library or a final executable. `The JavaScript target
<#backends-the-javascript-target>`_ can generate a ``.js`` file which you
reference from an HTML file or create a `standalone Node.js program
<http://nodejs.org>`_.
Objective-C targets and the JavaScript target. [The C like targets](
#backends-the-c-like-targets) creates source files that can be compiled
into a library or a final executable. [The JavaScript target](
#backends-the-javascript-target) can generate a ``.js`` file which you
reference from an HTML file or create a [standalone Node.js program](
http://nodejs.org).

On top of generating libraries or standalone applications, Nim offers
bidirectional interfacing with the backend targets through generic and
Expand Down Expand Up @@ -64,8 +64,8 @@ line invocations:
```

The compiler commands select the target backend, but if needed you can
`specify additional switches for cross-compilation
<nimc.html#crossminuscompilation>`_ to select the target CPU, operative system
[specify additional switches for cross-compilation](
nimc.html#crossminuscompilation) to select the target CPU, operative system
or compiler/linker commands.


Expand All @@ -89,15 +89,15 @@ available. This includes:
* some modules of the standard library
* proper 64-bit integer arithmetic

To compensate, the standard library has modules `catered to the JS backend
<lib.html#pure-libraries-modules-for-js-backend>`_
To compensate, the standard library has modules [catered to the JS backend](
lib.html#pure-libraries-modules-for-js-backend)
and more support will come in the future (for instance, Node.js bindings
to get OS info).

To compile a Nim module into a ``.js`` file use the `js`:option: command; the
default is a ``.js`` file that is supposed to be referenced in an ``.html``
file. However, you can also run the code with `nodejs`:idx:
(`<http://nodejs.org>`_):
(http://nodejs.org):

```cmd
nim js -d:nodejs -r examples/hallo.nim
Expand All @@ -120,14 +120,14 @@ component?).
Nim code calling the backend
----------------------------

Nim code can interface with the backend through the `Foreign function
interface <manual.html#foreign-function-interface>`_ mainly through the
`importc pragma <manual.html#foreign-function-interface-importc-pragma>`_.
Nim code can interface with the backend through the [Foreign function
interface](manual.html#foreign-function-interface) mainly through the
[importc pragma](manual.html#foreign-function-interface-importc-pragma).
The `importc` pragma is the *generic* way of making backend symbols available
in Nim and is available in all the target backends (JavaScript too). The C++
or Objective-C backends have their respective `ImportCpp
<manual.html#implementation-specific-pragmas-importcpp-pragma>`_ and
`ImportObjC <manual.html#implementation-specific-pragmas-importobjc-pragma>`_
or Objective-C backends have their respective [ImportCpp](
manual.html#implementation-specific-pragmas-importcpp-pragma) and
[ImportObjC](manual.html#implementation-specific-pragmas-importobjc-pragma)
pragmas to call methods from classes.

Whenever you use any of these pragmas you need to integrate native code into
Expand All @@ -139,19 +139,20 @@ However, for the C like targets you need to link external code either
statically or dynamically. The preferred way of integrating native code is to
use dynamic linking because it allows you to compile Nim programs without
the need for having the related development libraries installed. This is done
through the `dynlib pragma for import
<manual.html#foreign-function-interface-dynlib-pragma-for-import>`_, though
more specific control can be gained using the `dynlib module <dynlib.html>`_.
through the [dynlib pragma for import](
manual.html#foreign-function-interface-dynlib-pragma-for-import), though
more specific control can be gained using the [dynlib module](dynlib.html).

The `dynlibOverride <nimc.html#dynliboverride>`_ command line switch allows
The [dynlibOverride](nimc.html#dynliboverride) command line switch allows
to avoid dynamic linking if you need to statically link something instead.
Nim wrappers designed to statically link source files can use the `compile
pragma <manual.html#implementation-specific-pragmas-compile-pragma>`_ if
Nim wrappers designed to statically link source files can use the [compile
pragma](manual.html#implementation-specific-pragmas-compile-pragma) if
there are few sources or providing them along the Nim code is easier than using
a system library. Libraries installed on the host system can be linked in with
the `PassL pragma <manual.html#implementation-specific-pragmas-passl-pragma>`_.
the [PassL pragma](manual.html#implementation-specific-pragmas-passl-pragma).

To wrap native code, take a look at the `c2nim tool <https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst>`_ which helps
To wrap native code, take a look at the [c2nim tool](
https://github.com/nim-lang/c2nim/blob/master/doc/c2nim.rst) which helps
with the process of scanning and transforming header files into a Nim
interface.

Expand Down Expand Up @@ -223,16 +224,16 @@ from the previous section):
Compile the Nim code to JavaScript with `nim js -o:calculator.js
calculator.nim`:cmd: and open ``host.html`` in a browser. If the browser supports
javascript, you should see the value `10` in the browser's console. Use the
`dom module <dom.html>`_ for specific DOM querying and modification procs
or take a look at `karax <https://github.com/pragmagic/karax>`_ for how to
[dom module](dom.html) for specific DOM querying and modification procs
or take a look at [karax](https://github.com/pragmagic/karax) for how to
develop browser-based applications.


Backend code calling Nim
------------------------

Backend code can interface with Nim code exposed through the `exportc
pragma <manual.html#foreign-function-interface-exportc-pragma>`_. The
Backend code can interface with Nim code exposed through the [exportc
pragma](manual.html#foreign-function-interface-exportc-pragma). The
`exportc` pragma is the *generic* way of making Nim symbols available to
the backends. By default, the Nim compiler will mangle all the Nim symbols to
avoid any name collision, so the most significant thing the `exportc` pragma
Expand Down Expand Up @@ -347,8 +348,8 @@ Nimcache naming logic
The `nimcache`:idx: directory is generated during compilation and will hold
either temporary or final files depending on your backend target. The default
name for the directory depends on the used backend and on your OS but you can
use the `--nimcache`:option: `compiler switch
<nimc.html#compiler-usage-commandminusline-switches>`_ to change it.
use the `--nimcache`:option: [compiler switch](
nimc.html#compiler-usage-commandminusline-switches) to change it.


Memory management
Expand All @@ -366,15 +367,15 @@ aware of who controls what to avoid crashing.
Strings and C strings
---------------------

The manual mentions that `Nim strings are implicitly convertible to
cstrings <manual.html#types-cstring-type>`_ which makes interaction usually
The manual mentions that [Nim strings are implicitly convertible to
cstrings](manual.html#types-cstring-type) which makes interaction usually
painless. Most C functions accepting a Nim string converted to a
`cstring` will likely not need to keep this string around and by the time
they return the string won't be needed anymore. However, for the rare cases
where a Nim string has to be preserved and made available to the C backend
as a `cstring`, you will need to manually prevent the string data
from being freed with `GC_ref <system.html#GC_ref,string>`_ and `GC_unref
<system.html#GC_unref,string>`_.
from being freed with [GC_ref](system.html#GC_ref,string) and [GC_unref](
system.html#GC_unref,string).

A similar thing happens with C code invoking Nim code which returns a
`cstring`. Consider the following proc:
Expand All @@ -393,10 +394,10 @@ Custom data types

Just like strings, custom data types that are to be shared between Nim and
the backend will need careful consideration of who controls who. If you want
to hand a Nim reference to C code, you will need to use `GC_ref
<system.html#GC_ref,ref.T>`_ to mark the reference as used, so it does not get
freed. And for the C backend you will need to expose the `GC_unref
<system.html#GC_unref,ref.T>`_ proc to clean up this memory when it is not
to hand a Nim reference to C code, you will need to use [GC_ref](
system.html#GC_ref,ref.T) to mark the reference as used, so it does not get
freed. And for the C backend you will need to expose the [GC_unref](
system.html#GC_unref,ref.T) proc to clean up this memory when it is not
required anymore.

Again, if you are wrapping a library which *mallocs* and *frees* data
Expand Down
19 changes: 11 additions & 8 deletions doc/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@ must be marked as deprecated using the `deprecated` pragma:
```


See also `Deprecated <manual.html#pragmas-deprecated-pragma>`_
See also [Deprecated](manual.html#pragmas-deprecated-pragma)
pragma in the manual.


Expand All @@ -242,7 +242,7 @@ as well as `testament`:cmd: and guarantee they stay in sync.
result = a & "Bar"
```

See `parentDir <os.html#parentDir,string>`_ example.
See [parentDir](os.html#parentDir,string) example.

The RestructuredText Nim uses has a special syntax for including code snippets
embedded in documentation; these are not run by `nim doc`:cmd: and therefore are
Expand Down Expand Up @@ -297,7 +297,7 @@ the first is preferred.
When you specify an *RST role* (highlighting/interpretation marker) do it
in the postfix form for uniformity, that is after \`text in backticks\`.
For example an ``:idx:`` role for referencing a topic ("SQLite" in the
example below) from `Nim Index`_ can be used in doc comment this way:
example below) from [Nim Index] can be used in doc comment this way:

```nim
## A higher level `SQLite`:idx: database wrapper.
Expand Down Expand Up @@ -466,8 +466,8 @@ General commit rules

2. If you introduce changes which affect backward compatibility,
make breaking changes, or have PR which is tagged as ``[feature]``,
the changes should be mentioned in `the changelog
<https://github.com/nim-lang/Nim/blob/devel/changelog.md>`_.
the changes should be mentioned in [the changelog](
https://github.com/nim-lang/Nim/blob/devel/changelog.md).

3. All changes introduced by the commit (diff lines) must be related to the
subject of the commit.
Expand Down Expand Up @@ -525,8 +525,10 @@ Continuous Integration (CI)
documentation only changes), add ``[skip ci]`` to your commit message title.
This convention is supported by our GitHub actions pipelines and our azure pipeline
(using custom logic, which should complete in < 1mn) as well as our former other pipelines:
`Appveyor <https://www.appveyor.com/docs/how-to/filtering-commits/#skip-directive-in-commit-message>`_
and `Travis <https://docs.travis-ci.com/user/customizing-the-build/#skipping-a-build>`_.
[Appveyor](
https://www.appveyor.com/docs/how-to/filtering-commits/#skip-directive-in-commit-message)
and [Travis](
https://docs.travis-ci.com/user/customizing-the-build/#skipping-a-build).
2. Consider enabling CI (azure, GitHub actions and builds.sr.ht) in your own Nim fork, and
waiting for CI to be green in that fork (fixing bugs as needed) before
Expand Down Expand Up @@ -568,7 +570,8 @@ Code reviews
2. When reviewing large diffs that may involve code moving around, GitHub's interface
doesn't help much, as it doesn't highlight moves. Instead, you can use something
like this, see visual results `here <https://github.com/nim-lang/Nim/pull/10431#issuecomment-456968196>`_:
like this, see visual results [here](
https://github.com/nim-lang/Nim/pull/10431#issuecomment-456968196):
```cmd
git fetch origin pull/10431/head && git checkout FETCH_HEAD
Expand Down
3 changes: 2 additions & 1 deletion doc/destructors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,8 @@ Lifetime-tracking hooks

The memory management for Nim's standard `string` and `seq` types as
well as other standard collections is performed via so-called
"Lifetime-tracking hooks", which are particular `type bound operators <manual.html#procedures-type-bound-operators>`_.
"Lifetime-tracking hooks", which are particular [type bound operators](
manual.html#procedures-type-bound-operators).

There are 4 different hooks for each (generic or concrete) object type `T` (`T` can also be a
`distinct` type) that are called implicitly by the compiler.
Expand Down
54 changes: 27 additions & 27 deletions doc/docgen.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Introduction
============

This document describes the `documentation generation tools`:idx: built into
the `Nim compiler <nimc.html>`_, which can generate HTML, Latex and JSON output
the [Nim compiler](nimc.html), which can generate HTML, Latex 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 the module
dependencies (`import`), any top-level documentation comments (`##`), and
Expand Down Expand Up @@ -59,8 +59,8 @@ 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
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!
Basic Markdown syntax is also supported inside the doc comments.
Expand Down Expand Up @@ -148,7 +148,7 @@ Partial Output::
proc helloWorld(times: int) {.raises: [], tags: [].}
...

The full output can be seen here: `docgen_sample.html <docgen_sample.html>`_.
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.

Expand Down Expand Up @@ -247,7 +247,7 @@ Link text is either one word or a group of words enclosed by backticks `\``
Link text will be displayed *as is* while *link target* will be set to
the anchor \[*] of Nim symbol that corresponds to link text.

[*] anchors' format is described in `HTML anchor generation`_ section below.
\[*] anchors' format is described in [HTML anchor generation] section below.

If you have a constant:

Expand Down Expand Up @@ -435,11 +435,11 @@ 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.
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>`_
files in the specified directory to generate a [theindex.html](theindex.html)
file.

See source switch
Expand Down Expand Up @@ -488,7 +488,7 @@ the `rst2html`:option: and `rst2tex`:option: commands. Documents like this one a
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 a few other languages supported by the
`packages/docutils/highlite module <highlite.html>`_.
[packages/docutils/highlite module](highlite.html).

Usage:

Expand Down Expand Up @@ -550,38 +550,38 @@ Callable type Suffix

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>`_.
symbols in the [system module](system.html).

* `type SomeSignedInt = int | int8 | int16 | int32 | int64` **=>**
`#SomeSignedInt <system.html#SomeSignedInt>`_
[#SomeSignedInt](system.html#SomeSignedInt)
* `var globalRaiseHook: proc (e: ref E_Base): bool {.nimcall.}` **=>**
`#globalRaiseHook <system.html#globalRaiseHook>`_
[#globalRaiseHook](system.html#globalRaiseHook)
* `const NimVersion = "0.0.0"` **=>**
`#NimVersion <system.html#NimVersion>`_
[#NimVersion](system.html#NimVersion)
* `proc getTotalMem(): int {.rtl, raises: [], tags: [].}` **=>**
`#getTotalMem, <system.html#getTotalMem>`_
[#getTotalMem](system.html#getTotalMem)
* `proc len[T](x: seq[T]): int {.magic: "LengthSeq", noSideEffect.}` **=>**
`#len,seq[T] <system.html#len,seq[T]>`_
[#len,seq[T]](system.html#len,seq[T])
* `iterator pairs[T](a: seq[T]): tuple[key: int, val: T] {.inline.}` **=>**
`#pairs.i,seq[T] <iterators.html#pairs.i,seq[T]>`_
[#pairs.i,seq[T]](iterators.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>`_
[#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
Files with the ``.idx`` extension are generated when you use the [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>`_
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
[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
Expand Down Expand Up @@ -626,16 +626,16 @@ final index, and TOC entries found in ``.nim`` files are discarded.
Additional resources
====================

* `Nim Compiler User Guide <nimc.html#compiler-usage-commandminusline-switches>`_
* [Nim Compiler User Guide](nimc.html#compiler-usage-commandminusline-switches)

* Documentation for `rst module <rst.html>`_ -- Nim RST/Markdown parser.
* Documentation for [rst module](rst.html) -- Nim RST/Markdown parser.

* `RST Quick Reference
<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
* [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 the docgen output.

You can import the `packages/docutils/rstgen module <rstgen.html>`_ in your
You can import the [packages/docutils/rstgen module](rstgen.html) in your
programs if you want to reuse the compiler's documentation generation procs.
Loading

0 comments on commit f6ee066

Please sign in to comment.