* suppresses non-exported fields of types and adds command-line option to re-enable this if desired
* corrected the doctest that produced a CI error
* an embarrassingly bad error in reasoning
* modified a nimdoc test to reflect updated behavior
* needed another change to bring utils.html doctest in sync with update
* add info
* fix nimdoc
* lint
* render postfix
* fixes a problem
* fixes nimdoc
* fix nimdoc
---------
Co-authored-by: johnperry-math <john.perry@usm.edu>
Co-authored-by: johnperry-math <devotus@yahoo.com>
* docgen: implement cross-document links
Fully implements https://github.com/nim-lang/RFCs/issues/125
Follow-up of: https://github.com/nim-lang/Nim/pull/18642 (for internal links)
and https://github.com/nim-lang/Nim/issues/20127.
Overview
--------
Explicit import-like directive is required, called `.. importdoc::`.
(the syntax is % RST, Markdown will use it for a while).
Then one can reference any symbols/headings/anchors, as if they
were in the local file (but they will be prefixed with a module name
or markup document in link text).
It's possible to reference anything from anywhere (any direction
in `.nim`/`.md`/`.rst` files).
See `doc/docgen.md` for full description.
Working is based on `.idx` files, hence one needs to generate
all `.idx` beforehand. A dedicated option `--index:only` is introduced
(and a separate stage for `--index:only` is added to `kochdocs.nim`).
Performance note
----------------
Full run for `./koch docs` now takes 185% of the time before this PR.
(After: 315 s, before: 170 s on my PC).
All the time seems to be spent on `--index:only` run, which takes
almost as much (85%) of normal doc run -- it seems that most time
is spent on file parsing, turning off HTML generation phase has not
helped much.
(One could avoid it by specifying list of files that can be referenced
and pre-processing only them. But it can become error-prone and I assume
that these linke will be **everywhere** in the repository anyway,
especially considering https://github.com/nim-lang/RFCs/issues/478.
So every `.nim`/`.md` file is processed for `.idx` first).
But that's all without significant part of repository converted to
cross-module auto links. To estimate impact I checked the time for
`doc`ing a few files (after all indexes have been generated), and
everywhere difference was **negligible**.
E.g. for `lib/std/private/osfiles.nim` that `importdoc`s large
`os.idx` and hence should have been a case with relatively large
performance impact, but:
* After: 0.59 s.
* Before: 0.59 s.
So Nim compiler works so slow that doc part basically does not matter :-)
Testing
-------
1) added `extlinks` test to `nimdoc/`
2) checked that `theindex.html` is still correct
2) fixed broken auto-links for modules that were derived from `os.nim`
by adding appropriate ``importdoc``
Implementation note
-------------------
Parsing and formating of `.idx` entries is moved into a dedicated
`rstidx.nim` module from `rstgen.nim`.
`.idx` file format changed:
* fields are not escaped in most cases because we need original
strings for referencing, not HTML ones
(the exception is linkTitle for titles and headings).
Escaping happens later -- on the stage of `rstgen` buildIndex, etc.
* all lines have fixed number of columns 6
* added discriminator tag as a first column,
it always allows distinguish Nim/markup entries, titles/headings, etc.
`rstgen` does not rely any more (in most cases) on ad-hoc logic
to determine what type each entry is.
* there is now always a title entry added at the first line.
* add a line number as 6th column
* linkTitle (4th) column has a different format: before it was like
`module: funcName()`, now it's `proc funcName()`.
(This format is also propagated to `theindex.html` and search results,
I kept it that way since I like it more though it's discussible.)
This column is what used for Nim symbols resolution.
* also changed details on column format for headings and titles:
"keyword" is original, "linkTitle" is HTML one
* fix paths on Windows + more clear code
* Update compiler/docgen.nim
Co-authored-by: Andreas Rumpf <rumpf_a@web.de>
* Handle .md and .nim paths uniformly in findRefFile
* handle titles better + more comments
* don't allow markup overwrite index title for .nim files
Co-authored-by: Andreas Rumpf <rumpf_a@web.de>
* alternative, much simpler algorithm for strict func checking
* forgot to git add new compiler module
* new spec is incredibly simple to describe
* fixes bigints regression
* typos
* closes#16305; closes#17387; closes#20863
* fix issue #20922 by handling missing expr in `exprList` for `tkOf`
* fix line numbers in test case
* rewrite exprList requiring expr, add optionalExprList for except
As suggested by @metagn.
* update test case to reflect new code
* update grammar.txt
* update line numbers in test case taking into account nimout
Given the number of errors that are produced it seems easier to do it
this way instead of using `tt.Error`.
* Breaking parser changes, implement https://github.com/nim-lang/RFCs/issues/442
Types are separated from expressions and better reflected in the grammar.
* add test
* more accurate grammar
* fix keyword typedescs
* accept expressions in proc argument lists
* CI "fixes"
* fixes
* allow full ref expressions again, adapt old tests
* cleanup, fix some tests
* improve grammar, try and revert semtypes change
* restrict sigil binding to identOrLiteral
* fix, should have caught this immediately
* add changelog entry, fix double not nil bug
* correct grammar
* change section
* fix
* real fix hopefully
* fix test
* support LL(1) for tuples
* make grammar.txt too
* draft for let daa
* patch
* fixes bugs
* errors for global let variable reassignments
* checkpoint
* out param accepts let
* add more tests
* add documentation
* merge tests
* better procvar ambiguity errors, clean up after #20457fixes#6359, fixes#13849
* only trigger on closedsymchoice again
* new approach
* add manual entry for ambiguous enums too
* add indent [skip ci]
* move to proc
* fixes documentation regression and a bit clean up
follow up https://github.com/nim-lang/Nim/pull/20371
* Apply suggestions from code review
* Apply suggestions from code review
* Implement Markdown indented code blocks
Additional indentation of 4 spaces makes a block an "indented code block"
(monospaced text without syntax highlighting).
Also `::` RST syntax for code blocks is disabled.
So instead of
```rst
see::
Some code
```
the code block should be written as
```markdown
see:
Some code
```
* Migrate RST literal blocks :: to Markdown's ones
