summary refs log tree commit diff stats
path: root/lib/packages
Commit message (Collapse)AuthorAgeFilesLines
* fixes #21232; highlite.getNextToken() returns gtOperator for '/' in C (#21234)ringabout2023-01-081-0/+3
|
* docgen: implement cross-document links (#20990)Andrey Makarov2023-01-044-176/+452
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * 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>
* fix #19580; add warning for bare except: clause (#21099)ringabout2022-12-151-3/+3
| | | | | | | | | | | | | | | | | | | | | * fix #19580; add warning for bare except: clause * fixes some easy ones * Update doc/manual.md * fixes docs * Update changelog.md * addition * Apply suggestions from code review Co-authored-by: Jacek Sieka <arnetheduck@gmail.com> * Update doc/tut2.md Co-authored-by: Jacek Sieka <arnetheduck@gmail.com>
* fixes #20526; use `nimPreviewSlimSystem` for documentation build (#20714)ringabout2022-11-011-1/+1
| | | | | | | * fixes #20526; use `nimPreviewSlimSystem` for `koch docs` * fixes documentation errors * fixes remaning issues
* Markdown code blocks migration part 7 (#20547)Andrey Makarov2022-10-122-12/+13
|
* Make rstgen work with gcsafe (#20534)ringabout2022-10-101-4/+4
| | | | | | | | | | | * Make rstgen work with gcsafe Co-authored-by: Danil Yarantsev <tiberiumk12@gmail.com> * add tests and fixes * if nimHasWarningAsError Co-authored-by: Danil Yarantsev <tiberiumk12@gmail.com>
* Markdown indented code blocks (#20473)Andrey Makarov2022-10-053-19/+22
| | | | | | | | | | | | | | | | | | | | | | | * 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
* strutils, rstgen: avoid deprecated `strutils.delete` (#20488)ee72022-10-051-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The strutils `delete` func with signature func delete*(s: var string, first, last: int) was deprecated in adba5eb45e0a, in favor of one with signature func delete*(s: var string, slice: Slice[int]) However, a few procedures still used the deprecated form. This commit updates them, resolving these deprecation warnings: rstgen.nim(766, 12) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated] strutils.nim(1651, 19) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated] strutils.nim(1679, 7) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated] strutils.nim(2472, 7) Warning: use `delete(s, first..last)`; delete is deprecated [Deprecated] Before this commit: - `trimZeros` called `s.delete(i+1, i)` for an input that lacks a trailing zero (like "1.23"). - `removePrefix*(s: var string, prefix: string)` called `s.delete(0, -1)` when the prefix was the empty string. which did not modify `s`, nor raise an error. But the newer slice `delete` raises an `IndexDefect` when the start of the slice is greater than the end, so we avoid calling the new `delete` for such a case. Recall that exceptions inheriting from `system.Defect` are not tracked with the `.raises: []` exception tracking mechanism [1], so this commit does not break existing code like: proc foo {.raises: [].} = var s = "abc1.20" s.removePrefix("abc") s.trimZeros() doAssert s == "1.2" The `strutils.delete` deprecation was motivated by a problem with `system.delete` [2][3]: `system.delete` had surprising behavior when the index passed to it was out of bounds (it would delete the last entry then). Compile with `-d:nimStrictDelete` so that an index error is produced instead. Be aware however that your code might depend on this quirky behavior so a review process is required on your part before you can use `-d:nimStrictDelete`. To make this review easier, use the `-d:nimAuditDelete` switch, which pretends that `system.delete` is deprecated so that it is easier to see where it was used in your code. `-d:nimStrictDelete` will become the default in upcoming versions. A similar deprecation happened with `sequtils.delete` [4], but that deprecated form is already not used in this repo. [1] https://github.com/nim-lang/Nim/blob/2dec69fe5aa6/doc/manual.md#exception-tracking [2] https://github.com/nim-lang/Nim/blob/2dec69fe5aa6/changelogs/changelog_1_6_0.md#system [3] https://github.com/nim-lang/Nim/commit/92cb76571432 [4] https://github.com/nim-lang/Nim/commit/1d6863a7899f
* Extract markdown/rst doc into separate file (#20404)Andrey Makarov2022-09-221-221/+8
| | | | | | | | | | | * Extract Markdown & Rst doc into separate file This documentation should be extracted into separate file as it's user's documentation, which can be used as a separate utility for compiling `.md/.rst` files. * Restructure: move markup info into markdown_rst.md +Markdown link migration
* Implement Markdown definition lists (+ migration) (#20333)Andrey Makarov2022-09-113-8/+88
| | | | | | | | | | | | | | | Implements definition lists Markdown extension adopted in a few implementations including: * [Pandoc]( https://pandoc.org/MANUAL.html#definition-lists) * [kramdown]( https://kramdown.gettalong.org/quickref.html#definition-lists) * [PHP extra Markdown]( https://michelf.ca/projects/php-markdown/extra/#def-list) Also affected files have been migrated. RST definition lists are turned off for Markdown: this solves the problem of broken formatting mentioned in https://github.com/nim-lang/Nim/pull/20292.
* Markdown links migration part 1 (#20319)Andrey Makarov2022-09-091-3/+3
| | | | | | | | | | | | | 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 https://github.com/nim-lang/Nim/pull/20279, now they are working well (both in RST syntax and new Pandoc Markdown syntax implemented in https://github.com/nim-lang/Nim/pull/20304)
* fixes #9462; jsondoc --index can generate a theindex.json (#20205)ringabout2022-09-061-9/+8
|
* Implement Pandoc Markdown concise link extension (#20304)Andrey Makarov2022-09-044-40/+81
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * Implement Pandoc Markdown concise link extension This implements https://github.com/nim-lang/Nim/issues/20127. Besides reference to headings we also support doing references to Nim symbols inside Nim modules. Markdown: ``` Some heading ------------ Ref. [Some heading]. ``` Nim: ``` proc someFunction*() ... ... ## Ref. [someFunction] ``` This is substitution for RST syntax like `` `target`_ ``. All 3 syntax variants of extension from Pandoc Markdown are supported: `[target]`, `[target][]`, `[description][target]`. This PR also fixes clashes in existing files, particularly conflicts with RST footnote feature, which does not work with this PR (but there is a plan to adopt a popular [Markdown footnote extension](https://pandoc.org/MANUAL.html#footnotes) to make footnotes work). Also the PR fixes a bug that Markdown links did not work when `[...]` section had a line break. The implementation is straightforward since link resolution did not change w.r.t. RST implementation, it's almost only about new syntax addition. The only essential difference is a possibility to add a custom link description: form `[description][target]` which does not have an RST equivalent. * fix nim 1.0 gotcha
* Fix auto links to subheader when TOC is present (#20279)Andrey Makarov2022-08-272-91/+97
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Fix links to subheader when TOC is present It was observed (in https://github.com/nim-lang/Nim/pull/20112) that links to 2nd- (and subsequent) -level headings fail if TOC is present, e.g.: ```nim .. contents:: Type relations ============== Convertible relation -------------------- Ref. `Convertible relation`_ ``` The problem here is that links are resolved in `rst.nim` but later `rstgen.nim` fixes ("fixes") anchors to make them unique so that TOC always works (if e.g. there was another sub-section like "Convertible relation"). The solution implemented in this PR is to move that fix-up of anchors into `rst.nim`, so that link resolution could know final anchors. The bug seems to be added in https://github.com/nim-lang/Nim/pull/2332 in 2015, that is it is present in Nim 1.0.
* move formatfloat out of system (#20195)ringabout2022-08-241-1/+1
| | | | | | | | | | | | | | | * move formatfloat out of system * fixes doc * Update changelog.md * careless * fixes * deprecate system/formatfloat * better handling
* Add `doctype: RST|Markdown|RstMarkdown` pragma (#20252)Andrey Makarov2022-08-231-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | * Add `doctype: RST|Markdown|RstMarkdown` pragma Implements https://github.com/nim-lang/RFCs/issues/68 , see also discussion in https://github.com/nim-lang/Nim/issues/17987 The permitted values: * `markdown`, which is default. It still contains nearly all of the RST supported but it is assumed that in time we will give up most or all RST features in this mode * `rst`, without any extensions * `RstMarkdown` — compatibility with Nim 1.x. It's basically RST with those Markdown features enabled that don't conflict with RST. * Apply suggestions from code review Co-authored-by: Clay Sweetser <Varriount@users.noreply.github.com> * Additional fix in spirit of review * Fix test after #20188 Co-authored-by: Clay Sweetser <Varriount@users.noreply.github.com>
* Don't require blank line before Markdown code (#20215)Andrey Makarov2022-08-151-5/+11
| | | | Fixes bug reported in https://github.com/nim-lang/Nim/pull/20189 affecting nimforum.
* bootstrap the compiler with nimPreviewSlimSystem (#20176)ringabout2022-08-095-0/+21
| | | | | * bootstrap the compiler with nimPreviewSlimSystem * threads
* Highlight Nim default in Markdown code in .nim (#20110)Andrey Makarov2022-07-312-11/+16
| | | Highlight Nim by default in Markdown code in .nim
* Markdown code blocks part 2; migrate Nim Manual (#20080)Andrey Makarov2022-07-251-24/+30
| | | | | * Change headings underscored by `~~~` to `###` * Markdown code blocks part 2; migrate Nim Manual
* Improve Markdown code blocks & start moving docs to Markdown style (#19954)Andrey Makarov2022-07-152-36/+119
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | - add additional parameters parsing (other implementations will just ignore them). E.g. if in RST we have: .. code:: nim :test: "nim c $1" ... then in Markdown that will be: ```nim test="nim c $1" ... ``` - implement Markdown interpretation of additional indentation which is less than 4 spaces (>=4 spaces is a code block but it's not implemented yet). RST interpretes it as quoted block, for Markdown it's just normal paragraphs. - add separate `md2html` and `md2tex` commands. This is to separate Markdown behavior in cases when it diverges w.r.t. RST significantly — most conspicously like in the case of additional indentation above, and also currently the contradicting inline rule of Markdown is also turned on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and RST arbitrarily is a way to nowhere, we need to provide a way to fix the particular behavior. Note that still all commands have **both** Markdown and RST features **enabled**. In this PR `*.nim` files can be processed only in Markdown mode, while `md2html` is for `*.md` files and `rst2html` for `*.rst` files. - rename `*.rst` files to `.*md` as our current default behavior is already Markdown-ish - convert code blocks in `docgen.rst` to Markdown style as an example. Other code blocks will be converted in the follow-up PRs - fix indentation inside Markdown code blocks — additional indentation is preserved there - allow more than 3 backticks open/close blocks (tildas \~ are still not allowed to avoid conflict with RST adornment headings) see also https://github.com/nim-lang/RFCs/issues/355 - better error messages - (other) fix a bug that admonitions cannot be used in sandbox mode; fix annoying warning on line 2711
* RST: improve simple tables (#19859)Andrey Makarov2022-06-043-80/+209
| | | | | | | * RST: improve simple tables * nim 1.0 gotchas * Still allow legacy boundaries like `----`
* Fix bug 27 of #17340 (#19433)Andrey Makarov2022-02-072-32/+51
| | | | | | Fixes silent disappearance of Markdown (pseudo-)link when it's detected as unsafe protocol. Now it will be converted to plain text in spirit of [the specification](https://spec.commonmark.org/0.30/#links). For that sake the check for protocol is added to rst.nim also.
* Merge pull request from GHSA-ggrq-h43f-3w7mDominik Picheta2022-01-291-3/+19
| | | | This fixes a CVE (currently https://github.com/nim-lang/Nim/security/advisories/GHSA-ggrq-h43f-3w7m)
* RST: allow empty number-lines directives just like it was done for a decade; ↵Andreas Rumpf2022-01-221-1/+2
| | | | all my documents rely on this feature [backport (#19431)
* make rst thread safe (#19369)flywind2022-01-131-3/+3
| | | split for the convenience of review
* Fix group reference (with capital letters (#19196)Andrey Makarov2021-12-201-1/+1
| | | in group name)
* fixes a possible 'javascript:' protocol exploit [backport:1.0] (#19134)Andreas Rumpf2021-12-101-1/+14
| | | | | | | | | | | | | * fixes a possible 'javascript:' protocol exploit [backport:1.0] * add tests * Update tests/stdlib/trstgen.nim * add the same logic for hyperlinks * move the logic into a proc Co-authored-by: narimiran <narimiran@disroot.org>
* implement RST & Markdown quote blocks (#19147)Andrey Makarov2021-11-233-11/+237
| | | | | | | * implement RST & Markdown quote blocks * compile with nim 1.0 * Fix indentation
* fix nimindexterm in rst2tex/doc2tex [backport] (#19106)Andrey Makarov2021-11-091-1/+1
| | | | | * fix nimindexterm (rst2tex/doc2tex) [backport] * Add support for indexing in rst
* change os.nim doc links to new style (#19102)Andrey Makarov2021-11-081-4/+15
|
* docgen: implement doc link resolution in current module (#18642)Andrey Makarov2021-10-284-78/+540
|
* rst: minor fixes (#18960)Andrey Makarov2021-10-063-3/+4
|
* with this patch :idx: can be used for the index generation for LaTeX (#18946)Andreas Rumpf2021-10-031-1/+1
|
* [minor] reduce `substr` (#18611)flywind2021-07-301-1/+1
| | | | | | | | | * minor * correct * unify the type of addrLen * Update lib/packages/docutils/rstgen.nim
* rst: add missing line/column info for some warnings (#18383)Andrey Makarov2021-07-203-83/+158
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * rst: add missing line/column info for some warnings * add workaround * use TLineInfo/FileIndex for storing file names * fix blank lines in include file (rm harmful strip) * don't use ref TLineInfo * return `hasToc` as output parameter for uniformity * Update compiler/docgen.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update compiler/docgen.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update lib/packages/docutils/rst.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * address review - stylistic things * Update compiler/docgen.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * unify RST warnings/errors names * doAssert + minor name change * fix a bug caught by doAssert * apply strbasics.strip to final HTML/Latex * rm redundant filename * fix test after rebase * delete `order` from rnFootnoteRef, also display errors/warnings properly when footnote references are from different files * Update compiler/lineinfos.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update lib/packages/docutils/rstast.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update lib/packages/docutils/rstast.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update lib/packages/docutils/rstast.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * revert because of error: Error: cannot prove that it's safe to initialize 'info' with the runtime value for the discriminator 'kind' * Update lib/packages/docutils/rstgen.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * apply suggestion * Update lib/packages/docutils/rst.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * add Table for string->file name mapping * do not import compiler/lineinfos * fix ambiguous calls Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> Co-authored-by: narimiran <narimiran@disroot.org>
* rm redundant blank lines before literal blocks (#18465)Andrey Makarov2021-07-082-2/+2
|
* remove isKeywordIgnoreCase from highlite, not used , can't even compile with ↵Bung2021-06-301-3/+0
| | | | -d:useNimRtl (#18399)
* rst: fix bug 20 from #17340 (#18360)Andrey Makarov2021-06-261-1/+3
| | | and a leftover bug: priority of option list inside definition list
* rst: allow comment to continue on second line (#18338)Andrey Makarov2021-06-241-18/+10
|
* Markdown: allow to end URL with balanced parenthesis (#18321)Andrey Makarov2021-06-231-2/+34
| | | | | | | | | | | | | * Markdown: allow to end URL with balanced parenthesis * Update lib/packages/docutils/rst.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * apply suggestion * remove unnecessary if Co-authored-by: Timothee Cour <timothee.cour2@gmail.com>
* validate rst field for :number-lines:, :status: (#18304)Andrey Makarov2021-06-202-8/+23
|
* docgen: move to shared RST state (fix #16990) (#18256)Andrey Makarov2021-06-201-97/+118
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * docgen: move to shared RST state (fix #16990) * Update lib/packages/docutils/rst.nim Co-authored-by: Andreas Rumpf <rumpf_a@web.de> * Update lib/packages/docutils/rst.nim Co-authored-by: Andreas Rumpf <rumpf_a@web.de> * Update lib/packages/docutils/rst.nim Co-authored-by: Andreas Rumpf <rumpf_a@web.de> * Update compiler/docgen.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update compiler/docgen.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update compiler/docgen.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * Update lib/packages/docutils/rst.nim Co-authored-by: Timothee Cour <timothee.cour2@gmail.com> * rename `cmdDoc2` to `cmdDoc` * fix (P)RstSharedState convention * new style of initialization * misc suggestions * 1 more rename * fix a regression Co-authored-by: Andreas Rumpf <rumpf_a@web.de> Co-authored-by: Timothee Cour <timothee.cour2@gmail.com>
* rst: remove `roSkipPounds` option (#18175)Andrey Makarov2021-06-051-24/+4
|
* docs: Latex generation improvements (#18141)Andrey Makarov2021-06-012-62/+96
| | | | | | | * docs: improve Latex generation * make it work on Windows + fix ] escaping * minor fixes with escapes and style
* docs: make inline markup more compatible with Markdown (#18053)Andrey Makarov2021-05-211-48/+97
| | | fixes https://github.com/timotheecour/Nim/issues/739
* follow-up #17930 - inline syntax highlighting (#18013)Andrey Makarov2021-05-161-11/+14
| | | | | * follow-up #17930 - inline syntax highlighting * make closure->nimcall
* RST opt.list to have priority over def.list (#17845)Andrey Makarov2021-05-151-2/+2
|
* `doc2tex`: generate docs to Latex (#17997)Andrey Makarov2021-05-142-30/+33
| | | | | * `doc2tex`: generate docs to Latex * address some comments
* follow-up #17837: add `Console` for interactive sessions (#17930)Andrey Makarov2021-05-062-14/+33
| | | | | * follow-up #17837: add `Console` for interactive sessions * fix Latex
generated by cgit-pink 1.4.1-2-gfad0 (git 2.36.2.497.gbbea4dcf42) at 2025-02-07 22:24:08 +0000