Missing documentation on nimdoc.css #14424

FedericoCeratto · 2020-05-21T21:39:33Z

nim doc fails to run when nimdoc.css is not found. The error message does not indicate how to configure the correct path
There is no mention of the path for nimdoc.css in nimdoc.cfg
...or in the manual
Removing $nimdoccss from the HTML template in nimdoc.cfg does not fixes nim doc
compiler/docgen.nim sets the path to d.conf.getPrefixDir() / "doc" / "nimdoc.css" apparently without a way to override it

The text was updated successfully, but these errors were encountered:

timotheecour · 2020-05-22T13:07:48Z

please always try on latest devel when reporting issues and mention the corresponding hash; it saves time for whoever's looking at bug reports; also, a sample command would help for a reproducible bug report
IIRC some of these issues should've already been fixed in devel, but hard to tell without a git hash
fix #6583, fix #14376, index+search now generated for all projects, many bug fixes with nim doc #14324 should fix at least some of the issues you're mentioning; please try against that and let me know if you still have issues

kaushalmodi · 2020-05-22T13:29:25Z

The issue can be reproduced if the doc/ directory is missing in the nim installation:

oserr.nim(94)            raiseOSError
Error: unhandled exception: No such file or directory
Additional info: "/home/kmodi/nim/1.2.0/doc/nimdoc.css" [OSError]

But the error is also now more informative.

This issue is probably a duplicate of #13191.

kaushalmodi · 2020-05-22T13:39:52Z

@timotheecour This makes me think.. as the nim doc relies on the existence of that nimdoc.css, is the doc/ directory the best place for that? Should it rather live along with other sources, may be in lib/ or compiler/ ?

timotheecour · 2020-05-22T13:46:20Z

how was /home/kmodi/nim/1.2.0 installed?
with choosenim I have:
/Users/timothee/.choosenim/toolchains//nim-1.2.0/doc/nimdoc.css

is the doc/ directory the best place for that? Should it rather live along with other sources, may be in lib/ or compiler/ ?

one could make a case for either doc or lib but it probably shouldn't matter much so long nim installation installs the correct files; note that I'm also relying on dochack/dochack.{nim or js} existing for #14324

kaushalmodi · 2020-05-22T13:50:11Z

how was /home/kmodi/nim/1.2.0 installed?

I admit that it was using my local script that creates a minimal installation footprint of nim for my work.

Just for nim doc to work, I need this in my script:

cp -fP "${nim_download_dir}"/doc/*.css ./doc/. # Required for 'nim doc ..' to work

It feels rather odd that something that nim binary relies on, lives in the usually discardable (for other tools) doc/ dir.

kaushalmodi · 2020-05-22T13:56:01Z

note that I'm also relying on dochack/dochack.{nim or js} existing for #14324

I am looking forward to see the outcome of that PR. Right now, I have a custom config.nims docs task that Does The Right Thing :)

timotheecour · 2020-05-22T14:09:40Z

I'm fine with the idea of a miminal footprint install, but this really should be done via some API (tested in testament), not by guessing which files to include, otherwise things are guaranteed to break at some point (like here); nim should have some freedom to keep internal details as implementation details, while providing an API to do things like that.

That's the more robust thing IMO (moving around nimdoc.css would not address future internal changes, including that new dochacks.nim/js dependency)

I am looking forward to see the outcome of that PR

the idea is for index+search to "just work" for any project with a single command (and making --index on be new default soon after)

have a custom config.nims docs task that Does The Right Thing :)

hopefully #14324 will simplify your script and make it more robust :) (dochack.nim should be tied to your nim repo, not to a fixed origin like "https://nim-lang.github.io/Nim/dochack.js eg to keep dochack.nim consistent with your local changes; also #14324 handles --project

one thing I've left as TODO is fixing href's to dochack.js in case of nested dirs; help welcome there

closing this issue

So what's needed to close this PR, assuming that OP was using non standard installation if I'm reading #14424 (comment) correctly? we already have ./koch zip, do we need ./koch zip --minimal ?

kaushalmodi · 2020-05-22T14:18:05Z

I'll let the OP comment on if this issue can be closed. For me, personally, I understood the risks, and adapted the minimal download script for my own use. I don't think that the koch should be cluttered with that switch.

kaushalmodi · 2020-05-22T14:20:10Z

hopefully #14324 will simplify your script and make it more robust :) (dochack.nim should be tied to your nim repo, not to a fixed origin like "https://nim-lang.github.io/Nim/dochack.js eg to keep dochack.nim consistent with your local changes; also #14324 handles --project

+1

I will follow the development of that PR. I looks like a much involving PR, so I probably cannot help much there. But I can help test out the PR. We can continue discussion about that PR in its thread.

FedericoCeratto · 2020-05-24T19:14:23Z

@timotheecour the issue was found in this nightly build: https://github.com/nim-lang/nightlies/releases/tag/2020-05-20-version-1-2-7800fa3 which is designate as rc1 for 1.2.2

FedericoCeratto · 2020-05-24T19:18:55Z

Note to self: https://nim-lang.github.io/Nim/packaging.html should be updated with the solution

shirleyquirk · 2021-03-27T20:19:27Z

compiler expects nimdoc.css to be in the same tree as system.nim

Nim/compiler/nimpaths.nim

Lines 23 to 24 in 5d95137

    
           docCss* = "$nimr/doc/nimdoc.css" 
        
           docHackNim* = "$nimr/tools/dochack/dochack.nim"

i.e. /usr/lib/nim/doc

but no mention of this in docs and absent instructions to the contrary e.g. Arch puts them under /usr/share/nim/doc

https://forum.nim-lang.org/t/7679

timotheecour · 2021-03-27T20:24:21Z

@shirleyquirk please cross-link to avoid splitting discussion; i did it for you here: https://forum.nim-lang.org/t/7679#48913

choosenim installs it to:
/Users/timothee/.choosenim/toolchains//nim-1.4.4/doc/nimdoc.css

Arch puts them under /usr/share/nim/doc

maybe that's the bug?

can you show output of

find /usr/share/nim/ ?

shirleyquirk · 2021-03-27T23:13:39Z

Debian (sid,unstable, 1.4.2) puts it in /usr/lib/nim/doc, which probably doesn't work, either. arch provides a symlink meaning /usr/lib/nim/doc/nimdoc.css exists, referencing a bug from version 0.13 and the 'nim doc2' command.

installation instructions say "The expected stdlib location is /usr/lib/nim" which is sensible.
I know @timotheecour is familiar with this as i see you've worked on this problem already! just familiarizing myself, and not remotely aware of all the ramifications but:
i see docCss is hardcoded as $nimr/doc/nimdoc.css
$nimr is calculated based on the location of the nim binary:

Nim/compiler/options.nim

Lines 627 to 640 in 64e6670

    
           proc setDefaultLibpath*(conf: ConfigRef) = 
        
             # set default value (can be overwritten): 
        
             if conf.libpath.isEmpty: 
        
               # choose default libpath: 
        
               var prefix = getPrefixDir(conf) 
        
               when defined(posix): 
        
                 if prefix == AbsoluteDir"/usr": 
        
                   conf.libpath = AbsoluteDir"/usr/lib/nim" 
        
                 elif prefix == AbsoluteDir"/usr/local": 
        
                   conf.libpath = AbsoluteDir"/usr/local/lib/nim" 
        
                 else: 
        
                   conf.libpath = prefix / RelativeDir"lib" 
        
               else: 
        
                 conf.libpath = prefix / RelativeDir"lib"

so if the compiler binary is in /usr/bin/nim then the compiler expects to find nimdoc.css under /usr/doc/nimdoc.css
and if /usr/local/bin/nim then /usr/local/doc/nimdoc.css

it would be antisocial to put nims docs under /usr/doc meaning the whole nim tree would have to go under /opt with the other antisocial packages, but that would require changes to all distro's installations

the path of least resistance is probably to add a check here in docgen.nim to look under nimr/lib/nim as well if file not found?

timotheecour · 2021-03-27T23:32:58Z

can't we fix the distro's installation scripts so that they don't shuffle the installation files in a platform specific way? there are other things besides nimdoc.css that need to be in a specific location (eg dochack.js, in the future more things as well eg if we want to use karax for nim doc, etc)

in ideal world, every installed nim (via choosenim or otherwise) respects the original layout

shirleyquirk · 2021-03-28T12:02:52Z

yes, that's possible, change the packaging instructions to put the whole nim tree in /opt or somewhere. i dont like that solution, it multiplies the amount of work by the number of distros, would probably break a lot of users installations, and goes against conventional expectations (binary under /usr/bin, library under /lib, headers under /usr/include) it's understandable that a packager would expect 'doc' to contain the documentation, indeed it's listed as optional in the packaging info, but if nimdoc.css and dochack etc are requirements for the toolchain, they should live under /lib/nim imho.

timotheecour · 2021-03-28T15:49:48Z

can you point to the source code where those packaging instructions are written?

shirleyquirk · 2021-03-28T18:35:21Z

https://github.com/nim-lang/Nim/blob/devel/doc/packaging.rst

kaushalmodi · 2021-05-27T11:08:19Z

@shirleyquirk

they should live under /lib/nim imho

I agree! As I mentioned earlier, to anyone unknown with this special dependency, the doc directory would look like something optional and not a requirement for Nim commands to work.

@timotheecour Can the doc related files like css and js be moved to a doc/ subdir in lib?

timotheecour · 2021-05-27T17:10:03Z

https://github.com/nim-lang/Nim/blob/devel/doc/packaging.rst

these instructions are out of date, and should be updated (eg to use sh build_all.sh among other things)
we in fact shouldn't rely on bash commands to run by hand, this should be abstracted out by ./koch command instead of things like this:

for fn in nimble nimsuggest nimgrep; do cp ./bin/$fn <tempdir>/nim/bin/; done

they should live under /lib/nim imho

where would like like nimdoc.css to be inside nim repo?
($nim/lib/nim does not exist)

there are other dependencies besides $nim/lib eg $nim/tools/dochack/dochack.nim

again, ideally files are copied as is so that relative paths wrt nim binary work regardless of the installation platform; that said, it would be ok to reorganize a bit some of files nim relies on so that they're all inside some subdirectory of $nim/ (or installation instructions could simply copy the whole tree $nim/ for simpliicty)

kaushalmodi · 2021-05-27T17:13:37Z

($nim/lib/nim does not exist)

I actually meant $nim/lib/doc/. Can that hierarchy be created if it doesn't exist?

timotheecour · 2021-05-27T17:18:10Z

I'd be ok with $nim/lib/extras/ or $nim/extras/ as it shouldn't be restricted to doc stuff
there are 2 option:

option 1: extras=$nim/lib/extras/
option 2: extras=$nim/extras/

with either option we can write a PR as follows:

cd $nim
mkdir $extras
mv tools/dochack $extras
mv doc/nimdoc.css $extras
mv doc/{advopt.txt,basicopt.txt} $extras # technically not needed but cleaner
update references

anything else missing?

note that option 1 vs 2 matters because of the nim --lib:pathtolib flag, ie, with option 1, you'd expect paths under $extras to honor --lib, with option 2, those paths would honor nim binary location, not --lib

kaushalmodi · 2021-05-28T17:41:33Z

@timotheecour

option 1 vs 2 matters because of the nim --lib:pathtolib flag

This makes it less appealing to ship the .css file in the lib/ dir. I would expect nim doc .. command to Just Work whether or not the user uses --lib:<..>.

So this leads me to https://tldp.org/HOWTO/HighQuality-Apps-HOWTO/fhs.html .. Would it then be better to put things in /etc/nim/? It essentially what you suggested : extras/ but with a more standard name for Linux distributions.

etc/:
Contains configuration files. If your Software uses several files, put them under a subfolder like /etc/myproduct/

timotheecour · 2021-05-28T22:13:06Z

This makes it less appealing to ship the .css file in the lib/ dir. I would expect nim doc .. command to Just Work whether or not the user uses --lib:<..>.

that's not what I'm saying; --lib is an optional flag controlling location of lib folder which can override the one inferred otherwise from nim binary:

nim doc main # lib = $nimbinary.parendDir.parendDir/"lib"
nim doc --lib:pathtolib main # lib = pathtolib

it boils down to whether extras are tied to nim binary or to stdlib distribution

cvanelteren · 2021-07-07T07:37:34Z

I am running arch, and I am new to nim. Today, I ran into the issue when attempting to generate docs, how can I fix this?

timotheecour · 2021-07-07T08:54:52Z

how can I fix this?

PR welcome to proceed as described here: #14424 (comment)

shirleyquirk · 2021-07-07T16:30:26Z

$nim is /usr if the nim binary is /usr/bin/nim and it's the root directory (!) if the binary is in /bin/nim it's not appropriate to add folders or files either of those places.

/usr/lib/nim/ or /etc/nim are reasonable, but neither of the options proposed by @timotheecour.

cd $nim/lib
mkdir nim
mkdir nim/extras
# or mkdir nim_extras ?
...

Is what I'm proposing, would that be acceptable?

timotheecour · 2021-07-07T17:00:42Z

$nim is /usr if the nim binary is /usr/bin/nim and it's the root directory (!) if the binary is in /bin/nim it's not appropriate to add folders or files either of those places.

see how setDefaultLibpath is implemented, it infers $lib from nim binary but also takes into account a few hard coded locations so that it does the right thing eg:
if nim is in /usr/bin/nim, $lib will be /usr/lib/nim

right now it doesn't handle /bin/nim but this could be done if support for this is needed
the problem is that only $lib is remapped correctly, not $nim, so anything under $lib would result in relative paths resolving correctly between clone and installation, but for paths under $nim this currently doesn't work.
$nim/lib/extras/ would therefore be an easy solution, but one problem is that this won't have desirable semantics when user passes --lib flag, as files like nimdoc.css should be tied to compiler binary, not to the standard library

We could apply a similar logic to getPrefixDir as the one done for setDefaultLibpath (factoring out common code), that way, $nim resolves correctly regardless of whether it's from a clone or from an installation, but that would break relative paths of the form ../ from a path in lib to a path in extras.

Given that, why can't we just copy all whitelisted files during installation by retaining the original layout?

example 1:

nim binary:
/usr/bin/nim

$nim becomes:
/usr/lib/nim
and contains everything that's whitelisted, without messing with original layout:
/usr/lib/nim/doc/advopt.txt
/usr/lib/nim/lib/system.nim
/usr/lib/nim/nimbase.h
/usr/lib/nim/doc/nimdoc.css

example 2:

nim binary:
/usr/local/bin/nim
ditto, you'd have
/usr/local/lib/nim/doc/nimdoc.css
etc

this would work regardless of whether extras goes under $nim/extras or $nim/lib/extras (and extras wouldn't even be needed anymore), and relative paths (including with ..) would keep working.

FedericoCeratto · 2021-08-08T22:20:04Z

Workaround: Locate the files in the Nim sources and copy them to:

/usr/doc/nimdoc.css
/usr/tools/dochack/dochack.nim
/usr/tools/dochack/fuzzysearch.nim

Then compile dochack in the same directory nim js -d:release /usr/tools/dochack/dochack.nim

FedericoCeratto · 2021-09-26T13:44:40Z

nim doc is used to generate documentation for both the compiler itself but also 3rd party libraries and tool.
People should be able to supply custom nimdoc.css files for each project by overriding the default file path.

Regardless, the default paths in the Nim codebase should allow overriding by package maintainers. Nim should not hardcode paths in undocumented consts or make assumptions or guesswork.
The locations should be documented in https://github.com/nim-lang/Nim/blob/devel/doc/packaging.rst.

Can we gather all the "const" paths in a single installation_paths.nim file for easy patching (at packaging time)?

xlxs4 · 2022-08-03T14:02:02Z

Are there any updates/proposed workarounds for this?

calroc · 2022-09-29T01:50:03Z

I just ran into this on FreeBSD (12.3-RELEASE)

Nimdoc expects: /usr/local/doc/nimdoc.css but pkg install nim installs: /usr/local/share/doc/nim/nimdoc.css

sforman@bock:~/... % nim doc joy.nim
Hint: used config file '/usr/local/etc/nim/nim.cfg' [Conf]
Hint: used config file '/usr/local/etc/nim/nim.cfg' [Conf]
Hint: used config file '/usr/local/etc/nim/nimdoc.cfg' [Conf]
......................................................................................................................................................oserr.nim(95)            raiseOSError
Error: unhandled exception: No such file or directory
Additional info: /usr/local/doc/nimdoc.css [OSError]

Workaround was to create the expected dir and a symlink to the CSS file:

root@bock:/usr/local # mkdir doc
root@bock:/usr/local # cd doc
root@bock:/usr/local/doc # ln -s /usr/local/share/doc/nim/nimdoc.css

lbartoletti · 2022-10-26T18:46:31Z

I just ran into this on FreeBSD (12.3-RELEASE)

Nimdoc expects: /usr/local/doc/nimdoc.css but pkg install nim installs: /usr/local/share/doc/nim/nimdoc.css

sforman@bock:~/... % nim doc joy.nim
Hint: used config file '/usr/local/etc/nim/nim.cfg' [Conf]
Hint: used config file '/usr/local/etc/nim/nim.cfg' [Conf]
Hint: used config file '/usr/local/etc/nim/nimdoc.cfg' [Conf]
......................................................................................................................................................oserr.nim(95)            raiseOSError
Error: unhandled exception: No such file or directory
Additional info: /usr/local/doc/nimdoc.css [OSError]

Workaround was to create the expected dir and a symlink to the CSS file:

root@bock:/usr/local # mkdir doc
root@bock:/usr/local # cd doc
root@bock:/usr/local/doc # ln -s /usr/local/share/doc/nim/nimdoc.css

for previous version, I wrote this patch

nealie · 2022-11-25T10:24:56Z

I just ran into this on FreeBSD (12.3-RELEASE)
Nimdoc expects: /usr/local/doc/nimdoc.css but pkg install nim installs: /usr/local/share/doc/nim/nimdoc.css

sforman@bock:~/... % nim doc joy.nim
Hint: used config file '/usr/local/etc/nim/nim.cfg' [Conf]
Hint: used config file '/usr/local/etc/nim/nim.cfg' [Conf]
Hint: used config file '/usr/local/etc/nim/nimdoc.cfg' [Conf]
......................................................................................................................................................oserr.nim(95)            raiseOSError
Error: unhandled exception: No such file or directory
Additional info: /usr/local/doc/nimdoc.css [OSError]

Workaround was to create the expected dir and a symlink to the CSS file:

root@bock:/usr/local # mkdir doc
root@bock:/usr/local # cd doc
root@bock:/usr/local/doc # ln -s /usr/local/share/doc/nim/nimdoc.css

for previous version, I wrote this patch

I believe that I've just fixed this for FreeBSD with the upcoming update of lang/nim to 1.6.10. It took some "cheating" during the port build as the code seems to have some very fixed ideas about where things should be, which are unfortunately places not allowed in FreeBSD. The installation does not require any links though, so it's relatively clean.

timotheecour added the Documentation Generation Related to documentation generation (but not content). label May 22, 2020

shirleyquirk mentioned this issue May 7, 2021

Move choosenim under Nim org nim-lang/RFCs#374

Closed

FedericoCeratto mentioned this issue Aug 8, 2021

nim js ignores file write error #18662

Closed

FedericoCeratto mentioned this issue Dec 15, 2022

Move stdlib default path on Linux/posix #21112

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Missing documentation on nimdoc.css #14424

Missing documentation on nimdoc.css #14424

FedericoCeratto commented May 21, 2020

timotheecour commented May 22, 2020 •

edited

Loading

kaushalmodi commented May 22, 2020

kaushalmodi commented May 22, 2020

timotheecour commented May 22, 2020

kaushalmodi commented May 22, 2020 •

edited

Loading

kaushalmodi commented May 22, 2020

timotheecour commented May 22, 2020 •

edited

Loading

kaushalmodi commented May 22, 2020

kaushalmodi commented May 22, 2020

FedericoCeratto commented May 24, 2020

FedericoCeratto commented May 24, 2020

shirleyquirk commented Mar 27, 2021

timotheecour commented Mar 27, 2021 •

edited

Loading

shirleyquirk commented Mar 27, 2021

timotheecour commented Mar 27, 2021

shirleyquirk commented Mar 28, 2021

timotheecour commented Mar 28, 2021

shirleyquirk commented Mar 28, 2021

kaushalmodi commented May 27, 2021

timotheecour commented May 27, 2021 •

edited

Loading

kaushalmodi commented May 27, 2021

timotheecour commented May 27, 2021 •

edited

Loading

kaushalmodi commented May 28, 2021

timotheecour commented May 28, 2021

cvanelteren commented Jul 7, 2021 •

edited

Loading

timotheecour commented Jul 7, 2021 •

edited

Loading

shirleyquirk commented Jul 7, 2021 •

edited

Loading

timotheecour commented Jul 7, 2021 •

edited

Loading

FedericoCeratto commented Aug 8, 2021

FedericoCeratto commented Sep 26, 2021 •

edited

Loading

xlxs4 commented Aug 3, 2022

calroc commented Sep 29, 2022

lbartoletti commented Oct 26, 2022

nealie commented Nov 25, 2022

Missing documentation on nimdoc.css #14424

Missing documentation on nimdoc.css #14424

Comments

FedericoCeratto commented May 21, 2020

timotheecour commented May 22, 2020 • edited Loading

kaushalmodi commented May 22, 2020

kaushalmodi commented May 22, 2020

timotheecour commented May 22, 2020

kaushalmodi commented May 22, 2020 • edited Loading

kaushalmodi commented May 22, 2020

timotheecour commented May 22, 2020 • edited Loading

closing this issue

kaushalmodi commented May 22, 2020

kaushalmodi commented May 22, 2020

FedericoCeratto commented May 24, 2020

FedericoCeratto commented May 24, 2020

shirleyquirk commented Mar 27, 2021

timotheecour commented Mar 27, 2021 • edited Loading

shirleyquirk commented Mar 27, 2021

timotheecour commented Mar 27, 2021

shirleyquirk commented Mar 28, 2021

timotheecour commented Mar 28, 2021

shirleyquirk commented Mar 28, 2021

kaushalmodi commented May 27, 2021

timotheecour commented May 27, 2021 • edited Loading

kaushalmodi commented May 27, 2021

timotheecour commented May 27, 2021 • edited Loading

kaushalmodi commented May 28, 2021

timotheecour commented May 28, 2021

cvanelteren commented Jul 7, 2021 • edited Loading

timotheecour commented Jul 7, 2021 • edited Loading

shirleyquirk commented Jul 7, 2021 • edited Loading

timotheecour commented Jul 7, 2021 • edited Loading

example 1:

example 2:

FedericoCeratto commented Aug 8, 2021

FedericoCeratto commented Sep 26, 2021 • edited Loading

xlxs4 commented Aug 3, 2022

calroc commented Sep 29, 2022

lbartoletti commented Oct 26, 2022

nealie commented Nov 25, 2022

timotheecour commented May 22, 2020 •

edited

Loading

kaushalmodi commented May 22, 2020 •

edited

Loading

timotheecour commented May 22, 2020 •

edited

Loading

timotheecour commented Mar 27, 2021 •

edited

Loading

timotheecour commented May 27, 2021 •

edited

Loading

timotheecour commented May 27, 2021 •

edited

Loading

cvanelteren commented Jul 7, 2021 •

edited

Loading

timotheecour commented Jul 7, 2021 •

edited

Loading

shirleyquirk commented Jul 7, 2021 •

edited

Loading

timotheecour commented Jul 7, 2021 •

edited

Loading

FedericoCeratto commented Sep 26, 2021 •

edited

Loading