-
Notifications
You must be signed in to change notification settings - Fork 89
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
Support for markdown in standalone pages #1110
base: master
Are you sure you want to change the base?
Conversation
Co-authored-by: Daniel Bünzli <[email protected]> Signed-off-by: Paul-Elliot <[email protected]>
Co-authored-by: Daniel Bünzli <[email protected]> Signed-off-by: Paul-Elliot <[email protected]>
Signed-off-by: Paul-Elliot <[email protected]>
Signed-off-by: Paul-Elliot <[email protected]>
Co-authored-by: Daniel Bünzli <[email protected]> Signed-off-by: Paul-Elliot <[email protected]>
Signed-off-by: Paul-Elliot <[email protected]>
This is meant to form a basis for documentation Co-authored-by: Daniel Bünzli <[email protected]> Signed-off-by: Paul-Elliot <[email protected]>
Signed-off-by: Paul-Elliot <[email protected]>
This will be useful if we also want a converter ocamldoc to markdown, eg to upstream the ocamllsp translation. Signed-off-by: Paul-Elliot <[email protected]>
I forgot to mention one of the challenge such change will lead to.
|
Features are easy to add and hard to remove. Personally I don't think this should be merged, I don't think I need to expand on this, the tradeoffs are listed in the document added to this PR and I think that allowing this only in odoc pages makes it even worse. |
I don't agree. Most projects already have files written using the markdown format: often a README or some documentation. If we stick to strict GFM, this PR is simply adding support to generate docs for files which were already there. I agree though that it is a step toward markdown support in docstrings, which would bring the question of the deprecation of ocamldoc. However, the adoption of markdown in documentation pages would be a good way to assess whether documentation writer prefer to write in markdown or in ocamldoc, without comitting too much on markdown. |
These files simply use markdown, not |
Your quotation is removing part of my sentence!
My point is that we could remove the commit that adds a new syntax for markdown files from this PR (this one) and see whether the community favors markdown to ocamldoc (despite the lacking features). If yes, it is a good hint that the markdown syntax is preferred. If not, we did not commit too much into markdown, and still have the nice feature that we can render |
It's quite evident that the markdown syntax will be preferred, since a lot of people won't bother learning something else, especially newcomers. But of course this glosses over all the problems that using markdown for documentation has.
I don't think that's the duty of |
I see a lot of docs written in markdown here for instance, which would benefit from being rendered by odoc in ocaml.org. I also think that having people actually writing docs is better than having a very good language to write them. Given the quality of your documentations, it is clear that not having markdown support is not stopping you from writing docs. I often wish I could use markdown syntax, mostly out of habits and better editor support, but I don't think that is a big problem for me either. Footnotes
|
There is a difference between rendering markdown and introducing a new language, hacked over a language whose syntactic structure and semantics only really works well to write simple webpages or text blurbs. Most of the time once you add the missing pieces you are no longer in the markdown philosophy and you get to a language with structures that are not far from ocamldoc itself. I think that if If there is a larger wish to move from
If we are to speculate then I strongly suspect that it's rather the lack of… documentation. It's all about education. Where is the nice tutorial on |
I think it is there: https://ocaml.org/docs/generating-documentation. I agree it is a bit minimal, and that is a good idea to improve it. Maybe it is not made visible enough on ocaml.org, but having it more visible often mean having other important subjects less visible... |
This PR is a revival of @dbuenzli's original PR on odoc-parser. Since the parser has been moved to the odoc repo, I think we should continue the discussion here.
As in the original PR, syntax for ocamldoc references in markdown is made like this:
[!Module]
; and syntax for heading labels follows pandoc's specification (which is also followed by several other markdown variants). Math and tables uses cmarkit's specification.However, there are the differences with @dbuenzli's PR:
In this PR, Markdown can be used only in standalone documentation pages, based on the extension (
md
vsmld
). (@dbuenzli's PR "sniffed" the syntax to determine whether it was ocamldoc or markdown.)Math and table support have been added.
The commit history has been split out in the following commits:
!modules
" syntax.This hopefully allows to remove features from this PR more easily, depending on how many of them we want as a first step.
(Most of the work has been authored by @dbuenzli. who was added as co-author of relevant commits. Let me know if that is the right way to do it!)
Note: there are already several projects that show interest for markdown support in odoc:
Please share your opinion on this new feature!