New Issue: Improve user expierence of 'mason doc' and 'chpldoc'

28206, "jabraham17", "Improve user expierence of 'mason doc' and 'chpldoc'", "2025-12-13T02:24:44Z"

In working on a mason package, I have found mason doc to be completely inadequate

The default mason doc output for my project

My curated output

My two main issues are:

  • the default output does not have the project name, it defaults to chpldoc
  • there is no way to customize the index page, you just have to live with what you get

The second one is a big deal, it means I can't integrate the generated docs into any existing docs easily, or adjust how the docs are ordered.

Rather than chpldoc being treated as tool to scrape docs information from chapel source files and produce rst files that I can integrate into my documentation, chpldoc serves as a one-shot tool to output a complete documentation archive. While I can tell chpldoc to just output the rst and then process it myself, this is a bit cumbersome.

I have created some workaround for this for myself. See my script, custom conf.py, and custom index.rst

I think there are few things we can do to improve things

  • fix the generated conf.py from chpldoc to be correct for a given project. write now we just copy in an unfilled in template (this is why the project name is wrong in the first screenshot, its hardcoded to chpldoc in third-party/chpl-venv/chpldoc-sphinx-project/source/conf.py)
  • add more knobs to chpldoc to allow for custom conf.py
    • if some of the first bullet is fixed and improved, this is less important. But for the savy user, maybe useful?
  • ability to tell chpldoc to use a custom index.rst
  • pipe all of these features through to mason doc, and implement [Feature Request]: add a `docopts` option to mason · Issue #28204 · chapel-lang/chapel · GitHub so that extra customization can be done
1 Like