-
Notifications
You must be signed in to change notification settings - Fork 189
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
Fix coqdoc section titles #1774
Conversation
@jdchristensen no preview unfortunately, however the built artefacts can be downloaded when the job is finished. That's how we inspected doc stuff before. I'll link it here when they finish. |
@Alizter Can I build the docs locally (easily)? |
@jdchristensen Yes, if you want to build with Dune you can do |
I added instructions on comments to STYLE.md. Despite the instructions in that file, I manually updated the TOC at the top, since I don't have doctoc installed. Hope I did it right... |
- They must come at the start of the line, and have nothing after them, not even *). - Two symbols, not three. - Open with << and close with >>, not the reverse.
I silenced all of the warnings coqdoc was generating, which were in fact valid warnings. Many of the pages look better now. The only other issue I noticed is that some Category library comments use unicode, and the charset in the html files (both the toc and the individual files) isn't set to utf, so the unicode symbols appear garbled. Is it easy to change the generated html to use unicode? |
@jdchristensen Don't worry about the TOC too much, we can fix it when we come across it. |
Regarding unicode, I think it might be possible but I'll have to look into it later. Please open an issue about it. |
The docs say that you need to pass one of |
I tried viewing this PR's STYLE.md on github, and the TOC link worked fine, so all is good. |
@jdchristensen To pass flags to Dune (>=3.8) you need to use the |
FTR, there is this extension on VSCode that I was using the get the TOC. I checked myself and your version is fine. |
I have verified that |
@jdchristensen something like this: --- a/theories/dune
+++ b/theories/dune
@@ -8,7 +8,8 @@
(name HoTT)
(package coq-hott)
(modules :standard)
- (flags -noinit -indices-matter -color on))
+ (flags -noinit -indices-matter -color on)
+ (coqdoc_flags :standard --utf8)) You'll have to do the same for contrib and tests if you want to pass the same args (prob not). |
Currently |
@jdchristensen AFAICT we don't use that anywhere in the CI or anywhere else. |
Actually here is the same thing in Dune: diff --git a/theories/dune b/theories/dune
index e033640d..b249275d 100644
--- a/theories/dune
+++ b/theories/dune
@@ -8,7 +8,8 @@
(name HoTT)
(package coq-hott)
(modules :standard)
- (flags -noinit -indices-matter -color on))
+ (flags -noinit -indices-matter -color on)
+ (coqdoc_flags -interpolate -utf8 --no-externals %{env:COQDOCEXTRAFLAGS=}))
; TODO: Tests |
@jdchristensen Sorry if I was not clear earlier. I think you can remove |
This causes: |
@jdchristensen That's completely fine. We don't use the coqdoc feature of Dune. I opened an issue about it #1733 but didn't do anything further. You can think of it as another way to check doc locally. But the CI is the main builder of doc. We could clean up our infra and add CI previews etc. however I don't have too much time to sink into this. Currently most of my time for HoTT is playing around with the new 0gpd yoneda :) |
I think I'm done now! |
I realized that I was using things like
(** * text here *)
incorrectly, causing headings to be much too long in the generated html documentation, so I fixed my mistakes. While I was at it, I found a few other places to fix.Is there a way to preview the coqdoc html documentation before merging?