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

Convert manual from Wiki to mld #951

Merged
merged 4 commits into from
May 2, 2024
Merged

Conversation

MisterDA
Copy link
Contributor

@MisterDA MisterDA commented Jun 9, 2022

This allows to view the manual offline, and I think access it from the new docs website.

Converted with:

sed -E \
    -e 's/^==== *(.*) *====/{3 \1}/g' \
    -e 's/^=== *(.*) *===/{2 \1}/g' \
    -e 's/^== *(.*) *==/{1 \1}/g' \
    -e 's/^= *(.*) *=/{0 \1}/g' \
    -e 's/\[\[(.*)\|(.*)]]/{{: \1 }\2}/g' \
    -e 's|//(.*)//|{e \1}|g' \
    -e 's/<<a_api text=".*" *\| module (.+)>>/in {!\1}/g' \
    -e 's/<<code language="ocaml" *\|/{[\n/g' \
    -e 's/<<code language="c" *\|/{@c[/g' \
    -e 's/>>/]}/g' \
    -e "s/\`\`(.*)''/“\1”/g" \
    -e 's/\.\.\./…/g' \
    "$@" | \
    perl -pe 's|{{{(.*?)}}}|[\1]|g'

and then some manual fixes for lists and tables.

One shortcoming is that odoc doesn't have support for tables (see ocaml/odoc#864 and ocaml-doc/odoc-parser#11 for a concrete syntax proposal). There could be more references too, now they're just inline code blocks. I don't know how well it'll play with the existing Lwt website and wikidoc.

@raphael-proust
Copy link
Collaborator

For personal projects and such I always use md and so I'm quite happy about this PR. However, we need to still be able to push documentation to the official website. Currently, the way this happens is through the wikidoc branch where everything is supposed to be in .wiki format.

We can try to use md2mld and wikidoc (ocaml-doc to wiki) but it'll likely be brittle and fail to handle some useful cases like tables and such. The pandoc conversion tool might be a better solution although it adds a significant dependency to deploying the doc.

Do you have ideas?

@smorimoto
Copy link
Member

There may be an option to wait until they are implemented. In fact, tables, nested lists, and so on are mandatory.

@MisterDA
Copy link
Contributor Author

Note that this uses the mld syntax (odoc's syntax for documentation), not Markdown. I believe you can use odoc to have it generate the documentation instead of wikidoc or md2mld. It would perhaps use some external tweaking to fit in the website style.

I think it would be great to have the manual accessible offline and through odig/odoc.

btw the docs/Makefile seems outdated.

@raphael-proust
Copy link
Collaborator

Oh yes indeed! I got confused and just read md where it clearly says mld. My bad.

The makefile is indeed outdated. In fact, generating the documentation is quite complicated right now because of conflicting version constraints between wikidoc, domainslib, and ppx. I think a full rehaul of the documentation build might be needed. And we can probably switch the documentation format at the same time.

@raphael-proust
Copy link
Collaborator

The tables don't seem to render when I build the doc locally. Is the version of odoc that supports tables already released? I have 2.2.0 locally and opam says that's the latest released version.

@raphael-proust
Copy link
Collaborator

You should add the dependency to odoc in the opam file.

@MisterDA
Copy link
Contributor Author

Tables will be part of odoc 2.3.0, currently in development and unreleased.

@raphael-proust
Copy link
Collaborator

Ok. I've added the odoc>=2.3.0 dependency in the opam file. Ping me when the new version is released.

@MisterDA
Copy link
Contributor Author

MisterDA commented Oct 3, 2023

odoc.2.3.0 has been released!

MisterDA and others added 4 commits April 15, 2024 17:16
This allows to view the manual offline. Converted with:

    sed -E \
        -e 's/^==== *(.*) *====/{3 \1}/g' \
        -e 's/^=== *(.*) *===/{2 \1}/g' \
        -e 's/^== *(.*) *==/{1 \1}/g' \
        -e 's/^= *(.*) *=/{0 \1}/g' \
        -e 's/\[\[(.*)\|(.*)]]/{{: \1 }\2}/g' \
        -e 's|//(.*)//|{e \1}|g' \
        -e 's/<<a_api text=".*" *\| module (.+)>>/in {!\1}/g' \
        -e 's/<<code language="ocaml" *\|/{[\n/g' \
        -e 's/<<code language="c" *\|/{@c[/g' \
        -e 's/>>/]}/g' \
        -e "s/\`\`(.*)''/“\1”/g" \
        -e 's/\.\.\./…/g' \
        "$@" | \
        perl -pe 's|{{{(.*?)}}}|[\1]|g'

and then some manual fixes for lists and tables.
@raphael-proust
Copy link
Collaborator

I tried this locally and it all builds fine and displays well. I'm in favour of merging, which I'll do shortly unless someone raises some concerns.

@smorimoto smorimoto merged commit 0e231d4 into ocsigen:master May 2, 2024
25 checks passed
@MisterDA MisterDA deleted the manual-mld branch May 2, 2024 18:21
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