Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SPAN.attachedType in toc should have no width #10857

Closed
AvdN opened this issue Mar 18, 2019 · 2 comments

Comments

Projects
None yet
2 participants
@AvdN
Copy link
Contributor

commented Mar 18, 2019

There is a SPAN with class attachedType in each table-of-contents entry in the documentation, that is invisible, but has width. Because of that some entries are wrapped for no apparent reason.

Example

When looking at the TOC of osproc you'll see:

execProcesses
exec
Process
startProcess

In this part of the toc, execProcess is one entry, and it gets wrapped, although it is shorter than execProcesses, because there is a SPAN element on that line with a long CDATA.

Expected Output

The toc entry should look like:

execProcesses
execProcess
startProcess

Possible Solution

The way to solve this is by adding the style display:none to the SPAN element. I see three possible ways to do this (presented in order of, what I consider, increased preference):

  1. change the style attribute in doc.item.toc in config/nimdoc.cfg to read: style="visibility:hidden;display:none"

  2. change the class attribute in doc.item.toc in config/nimdoc.cfg to read: class="attachedType hidden" (hidden is a class that is already in the included style sheet that only sets "display:none")

  3. includes the class attachedType in the stylesheet section of doc.file in config/nimdoc.cfg that reads:

.attachedType {
  display: none;
  visibility: hidden;
}

which makes the the style component from doc.item.toc superfluous.

Additional Information

Each of the above solutions will need to be accompanied by changes to the test nimdoc/testproject/expected/testproject.html and nimdoc/testproject/expected/subdir/subdir_b/utils.html.

Although the third solution might prevent the need for further changes to doc.item.toc if the style further changes, the test files still have to change because of the verbatim inclusion of the stylesheet in the HTML (instead of a LINK to a stylesheet)


I can make a PR for this (I wanted to look at generating the documentation locally anyway (and the test), in order to expiroment with some potential enhancements), but I would like to know if there is any preferential solution, or problem with my preferred solution (the third one), as e.g. I have no idea if there is a reason the style for attachedType is currently hard-coded.

@narimiran

This comment has been minimized.

Copy link
Member

commented Mar 18, 2019

First off: thank you for the detailed bug report and for following our template. It makes things much easier for us. (If only more people did that)

When it comes to documentation, I recommend using devel docs available at https://nim-lang.github.io/Nim/lib.html, which have lots of improved details — sometimes the things you see in stable docs will be already fixed there. (But that is not the case this time)

I have no idea if there is a reason the style for attachedType is currently hard-coded.

I haven't checked it but it could be just some copy-pasted stuff that might be there for no reason :D

I can make a PR for this

Please do (and ping me when it is ready for review). You can go for your third solution, if you think it is the best one.

Each of the above solutions will need to be accompanied by changes to the test ...

There is a -d:fixup flag which you can use which will automatically change those tests for you, e.g.
nim c -r -d:fixup nimdoc/tester

AvdN pushed a commit to AvdN/Nim that referenced this issue Mar 18, 2019

Anthon van der Neut
fixes nim-lang#10857 invisible span had width
The explicit style on the span.attachedType used in the toc was
removed. The included style sheet extended for this tag+class
with both the original visibility:hidden as well as display:none
to solve the issue.

Expected output files were update to reflect this change.
@AvdN

This comment has been minimized.

Copy link
Contributor Author

commented Mar 18, 2019

@narimiran Since you are subscribed to this issue, I probably don't have to ping you as the PR referenced this issue and added an automatic entry.

I started with koch test html but that failed (JsonParsingError) even before I changed anything. nim c-r nimdoc/tester.nim worked however, after I made my changes in the config, the same command failed as expected, Then I ran your nim c -r -d:fixup nimdoc/tester which also failed, but after that the nim c-r nimdoc/tester.nim worked and I committed/created the PR. (You probably know how to do that, the above might help someone (or myself), who comes (back) here looking for clues.)

Thanks

@narimiran narimiran closed this in 5c1c590 Mar 19, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.