Skip to content

Conversation

timotheecour
Copy link
Member

@timotheecour timotheecour commented May 29, 2020

update doc CI filter to include the files mostly likely to require doc rebuild

unlike previous attempt (https://github.com/nim-lang/Nim/pull/13853/files), this is much more targeted, just the usual suspects that affect docs the most.

EDIT: CI fails on windows, which is a reason why this PR is needed (catch issues on code PRs that introduce problem, not later); I suspect it's because nim doc --project compiler/nim fails on windows... investigating

refactor all workaround implementations of nativeToUnixPath into 1

(I still need to finish #13265)

added compiler/index.nim

because https://nim-lang.github.io/Nim/compiler/nim.html was very underwhelming
after this PR navigating to https://nim-lang.github.io/Nim/compiler/ will do something useful

removed template duplication in config/nimdoc.cfg

and made sure it all works; so there's only 1 template to update

added undocumented ./koch --docslocal:myhtmldocs

so you can build all the docs n 40s instead of 190s as follows:
./koch --nim:$nimb --docslocal:htmldocs2 --doccmd:skip --warnings:off --hints:off
which is useful during local development when you need to run this a few times

added lib/std/private/globs.nim

for internal use only only (ie for any module inside nim repo) for now, but aim is to eventually merge those into stdlib.os once API stabilizes; same spirit as compiler/pathutils except lib/std/private/ is the perfect staging place IMO if you need to use it from not just compiler/ but other places (eg kochdocs, koch, tools, compiler, other modules in stdlib etc), giving it some internal exposure to give a chance to fix API without breaking user code, before converting it.

private conveys exactly what it is: for internal use only, if you use it in your code outside of nim repo it may break at any time

  • added walkDirRecFilter
    that's IMO the better API, and the most flexible (and walkDirRec can later be implemented on top of it)
    It's a common requested feature (eg see recent thread Can I "prune" directories with walkDirRect? - Nim forum) and should be in stdlib; but I also needed it in this PR, see below

  • fix a bug in getDocList
    this was picking up all the nim files in various nimcache folders in my repo (eg those created by runnableExamples); noone noticed since these don't export any symbols and therefore don't end up in the docs, but nim doc was being run on all of these, and there were quite a lot, slowing down koch docs.

The clean way to filter is via a follow filter (ie "filter early" before recursing down a folder instead of filtering at the end which is less efficient), hence walkDirRecFilter

fix a bug in lib/std/time_t.nim

which was making docs CI fail on windows since the compiler docs were enabled

used a glob to generate the rst files; added back docstyle which wasn't being docgen'd

i added docstyle which seemed like an unintentional omission
I kept docs.rst out since it's just an include
ditto with nimfix which is dead for now ( :-( ), but I wouldn't mind showing it in docs, would increase likelihood it gets revived

=> that's why glob+blacklist is always better than whitelist

@timotheecour timotheecour force-pushed the pr_fix_ci_doc_path_filter branch from d895484 to 978de58 Compare May 31, 2020 07:15
@timotheecour timotheecour changed the title update doc CI filter to include the files mostly likely to require doc rebuild walkDirRecFilter, update doc CI filter, compiler/index.nim for docs + various other fixes May 31, 2020
@timotheecour timotheecour force-pushed the pr_fix_ci_doc_path_filter branch from 9a13252 to 536c1f8 Compare May 31, 2020 08:57
@timotheecour timotheecour marked this pull request as ready for review May 31, 2020 09:43
@Araq Araq merged commit 3cf88c2 into nim-lang:devel Jun 1, 2020
@timotheecour timotheecour deleted the pr_fix_ci_doc_path_filter branch June 1, 2020 21:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants