ocaml / ocaml/dune

Package pre-built sphinx docs with dune release tars

Open
#5,115 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

acknowledged enhancement help wanted
Dominant language
OCaml
Stars
1.9k
Forks
500
Avg merge
15h 21m
Merged PRs (30d)
277

Description

The default help provided by dune is not detailed enough.

It would be great if we could type dune help and this would open a browser window showing dune documentation. These would be the same docs you get by invoking make doc in dune source (essentially what you get at https://dune.readthedocs.io ).

We can't assume that people have sphinx installed on their local machine. So I'm not advocating that we build the docs when we install dune on a switch.

I am suggesting that we package up pre-built sphinx generated documentation into the opam tbz release files.

Precedent
For those who use the fish shell, if you type

$ help

It opens locally stored HTML documentation for the fish shell in your browser. (If you don't use fish, please install it momentarily to just try this out...)

Possible Issues
I built sphinx documentation and looked at it locally. Everything looks good.

However, it looks like there is a regression in the search feature on localhost. I get search results but I am not able to see the matching hits and their context. I understand that readthedocs provides full text search over and above the default sphinx browser search.


  • Do you think this feature is useful?
  • If so, would the dune team be interested in implementing it?
  • If the feature is considered useful but the dune team does not have the time, I can volunteer to implement this feature but I would appreciate some general pointers on how to proceed...

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the dune help entry point and the make doc workflow described in the issue, then trace how opam tbz release files are assembled. Done means pre-built Sphinx HTML documentation is included in releases and dune help opens it locally; check the reported localhost search behavior as part of validation.

Written by the indexing model from the issue text.

Assessment

Tech stack
ocaml
Domain
cli, documentation, release
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.