doc: odoc manual + API (wodoc migration, dev)#355
Draft
balat wants to merge 4 commits into
Draft
Conversation
Convert the wikicreole manual (docs/manual-wiki/*.wiki) to odoc .mld (intro, functors, ppx, jsx) + a curated docs/api.mld from docs/indexdoc, declared in package tyxml via docs/dune (documentation). Convert the <<a_api>>/<<a_manual>> references in the .mli/.ml doc comments to native odoc references. First step of the wodoc doc migration.
…ire wikidoc Add a declarative doc/wodoc config + doc/ README and a CI (doc.yml) that builds & deploys via `wodoc build`. The CI triggers ONLY on master (push -> dev) plus a manual dispatch for releases (e.g. ref=latest-mli-odoc, label=4.6.0, set_latest; the version-independent doc sources are overlaid from master) — so pushing a branch never deploys, and the site still shows dev + the released version. Drop the legacy ocamldoc/wikidoc machinery (docs/Makefile, docs/indexdoc, docs/manual-wiki/, the Makefile wikidoc target).
Drop the workflow_dispatch release path (label/ref/set_latest), the overlay-from-master step and the repoint-latest step. Stable versions are built by hand and committed to gh-pages at release time, so CI now only rebuilds and deploys the dev docs on a push to master. README updated to match.
opam install . --deps-only --with-doc already pulls odoc, so the explicit install was a no-op. Spotted by @raphael-proust in review (ocsigen/lwt#1109).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Migrate the TyXML documentation to odoc/wodoc (part of the ocsigen-wide
doc rationalization away from html_of_wiki/wikidoc).
What this branch adds
docs/{intro,functors,ppx,jsx}.mld— the manual, converted fromdocs/manual-wiki/*.wikito odoc syntax.docs/api.mld— curated API index (fromdocs/indexdoc).docs/dunewith(documentation (package tyxml))sodune build @doccompiles the manual + API together and
{{!page-X}}/{!Module}refs resolve.<<a_api>>/<<a_manual>>references in the.mli/.mldoc commentsconverted to native odoc references.
Notes
dune build @doc --profile release(the dev profile treatswarning 67, unused functor parameter, as an error).
they resolve on ocaml.org. The eliom "see also" link is relative.
wodocin theocsigen.github.iorepo andpublished under
ocsigen.org/wodoc/tyxml/.Draft: pending review of the rendered output before merge.