Building Chapel Documentation

The live Chapel web documentation lives at https://chapel-lang.org/docs/. All of the source for the documentation is in the chapel source repository, and this note talks about how those are organized and built into the html documentation seen on the website.

The easiest way to build the Chapel web documentation is to run the command make docs in the top level directory of your chapel Github clone. You may need to do a cd doc && make clobber && cd .. && make docs if this isn’t the first time you have done a make docs.

This will build all of the web-based documentation hierarchy including the language spec, module documentation, technical notes, etc. using chpldoc, sphinx, doxygen, and other Chapel-specific scripts. Once built, the documentation can be viewed by pointing a web browser at $CHPL_HOME/doc/html/index.html. See Organization of Chapel Documentation Sources below for a table that overviews which inputs feed into which parts of the web-based documentation.

The html documentation is also generated by the Github CI (continuous integration) process. You can go to your pull request in Github, click on “Checks”, then “Ci” (on the left), and then scroll down to see the “documentation” (at the very bottom). It enables you to download a zip file of the built documentation. This is particularly useful when reviewing someone else’s PR and wanting to see what the resulting documentation looks like (where the alternative is to check out their branch and build it yourself).

Recent and previous releases of the documentation can be found at https://chapel-lang.org/docs/. Use the version menu at the upper left to select between the last release and the current documentation for the upcoming release.

How the HTML is Generated

The Chapel documentation shown at https://chapel-lang.org/docs/ is generated in three different ways:

1. reStructuredText files (with a .rst extension) are converted into .html files via sphinx (https://sublime-and-sphinx-guide.readthedocs.io/).

2. Some comments and code from Chapel source files are converted into .rst files using chapel/tools/chpldoc/, which will leave out TODOs, FIXMEs, and other parts of the comments.

3. Comments and code from Chapel source files are converted into .rst files using chapel/doc/util/chpl2rst.py.

Contributing to the Chapel Documentation

See https://chapel-lang.org/contributing.html for general instructions on how to contribute to Chapel. Contributing to the documentation is similar except you will want to build the documentation (see above) and check the generated html files before creating a pull request. Also note that if you are editing .chpl files in the primers directory for example, you will need to Develop and test contributions locally.

Editing the Source .rst and .chpl files

The .chpl files are text files that can be edited with any text editor. See $CHPL_HOME/highlight/README.md for information about some available extensions for editors to highlight Chapel code.

The .rst files are also text. The Chapel files that are being converted into .rst files have rst text in comments. There are some previewers for .rst text in vscode and atom, but none of them are quite as useful as editing a .rst file in Github and using the preview option. The way to see all of the links that are created is to do the make docs. See Organization of Chapel Documentation Sources for specifics about which source files and tools are used to create the web-based Chapel documentation.

Files that live in a repository

Some of the documentation files are not converted into html files. Instead they are raw html files in the chapel-www repository (currently only accessible by core developers) or raw .rst files that live in the public Github repository.

Examples include:

• https://chapel-lang.org/contributing.html

• https://github.com/chapel-lang/chapel/blob/main/doc/rst/developer/bestPractices/ContributorInfo.rst

Linking within and between files

Linking within and between files in https://chapel-lang.org/docs/

• Create a label right before the target section heading, .. _section-label:.

• Use :ref:`section-label` elsewhere in the same document or in any other document that will end up in RST files in the docs/rst/ or test/release/examples/primers/ subdirectory trees.

• See https://github.com/chapel-lang/chapel/blob/main/test/release/examples/primers/interopWithC.chpl for an example of :ref:`readme-libraries` that links to the html for https://raw.githubusercontent.com/chapel-lang/chapel/main/doc/rst/technotes/libraries.rst. The rst source file has .. _readme-libraries: at the top.

Linking between files in https://chapel-lang.org/docs/ and html files in https://chapel-lang.org .

• Linking from an rst file to an html file directly in https://chapel-lang.org is done by naming the needed URL in the .rst file and using that name. Here are some examples:

.. _Chapel Developers: https://chapel.discourse.group/c/developers

.. _Chapel Users: https://chapel.discourse.group/c/users

.. _chapel-lang/chapel: https://github.com/chapel-lang/chapel

A reference to the “Chapel Developers” link later in this .rst file would have one backquote on either side of it and be followed by an underscore (e.g., `Chapel Developers`_). The link definition itself has two periods, a space, the link name, a colon, a space, and then the URL (e.g., .. _Chapel Developers: https://chapel.discourse.group/c/developers).

• Linking from one of the html files at https://chapel-lang.org such as https://chapel-lang.org/contributing.html can only be done by a core contributor. Post an inquiry to the Chapel Developers Discourse forum.

Organization of Chapel Documentation Sources

The file chapel/doc/rst/index.rst is the root file that sets up the structure of the documentation and results in the sidebar displayed on https://chapel-lang.org/docs/.

There is a strong correlation between the sidebar and the doc/rst/ subdirectories, except for lots of the stuff under Writing Chapel Programs.

Below, the various kinds of documentation are organized by how they are converted into .html files. The first column indicates the sidebar subheading the document is published under, the second column indicates the document name there, and the last column shows the source files in the repository.

Using Sphinx to convert .rst files to .html files

Sidebar subheading	Doc name in Sidebar	Source file(s)
COMPILING AND RUNNING CHAPEL	Quickstart Instructions	doc/rst/usingchapel/QUICKSTART.rst
COMPILING AND RUNNING CHAPEL	Using Chapel	doc/rst/usingchapel/*
COMPILING AND RUNNING CHAPEL	Platform-Specific Notes	doc/rst/platforms/*
COMPILING AND RUNNING CHAPEL	Technical Notes	doc/rst/technotes/*
COMPILING AND RUNNING CHAPEL	Tools	doc/rst/tools/*
COMPILING AND RUNNING CHAPEL	Docs for Contributors	doc/rst/developers/*
WRITING CHAPEL PROGRAMS	Quick Reference	doc/rst/language/reference.rst
WRITING CHAPEL PROGRAMS	Mason Packages	doc/rst/mason-packages
WRITING CHAPEL PROGRAMS	Chapel Users Guide (WIP)	doc/rst/users-guide
LANGUAGE HISTORY	Chapel Evolution	doc/rst/language/evolution.rst
LANGUAGE HISTORY	Documentation Archives	doc/rst/language/archivedSpecs.rst

Use chpl2rst.py on .chpl files and then sphinx to generate html

Sidebar subheading	Doc name in Sidebar	Source file(s)
WRITING CHAPEL PROGRAMS	Hello World Variants	doc/rst/meta/examples/index.rst + test/release/examples/hello*.chpl
WRITING CHAPEL PROGRAMS	Primers	doc/rst/meta/primers/index.rst + test/release/examples/primers/*.chpl

Use doxygen on .cpp files and then breathe and sphinx to generate html

Sidebar subheading	Doc name in Sidebar	Source file(s)
COMPILING AND RUNNING CHAPEL	Docs for Contributors–> Frontend Library API Docs	doc/rst/developer/compiler-internals/*

Use chpldoc on .chpl files and then sphinx to generate html

Sidebar subheading	Doc name in Sidebar	Source file(s)
WRITING CHAPEL PROGRAMS	Built-in Types and Functions	doc/rst/builtins + modules/internal/*.chpl
WRITING CHAPEL PROGRAMS	Standard Modules	doc/rst/modules/standard + modules/standard/*.chpl
WRITING CHAPEL PROGRAMS	Package Modules	doc/rst/modules/packages + modules/packages/*.chpl
WRITING CHAPEL PROGRAMS	Standard Layouts and Distributions	doc/rst/modules/layoutdist + modules/layouts/*.chpl + modules/dists/*.chpl

Creating a new entry in the documentation sidebar

To create a new entry in the documentation sidebar, you need to:

• edit the doc/rst/index.rst file to include the entry

• if the entry refers to a new index.rst file then make sure to connect to that

• edit the doc/Makefile to make sure any .rst or .html files that need to be generated are generated when make docs happens

See the following github diff for an example of how to do this, https://github.com/mstrout/chapel/compare/e858449…newDocCategoryLikePrimers. The specified diff was never merged. It is just to illustrate the kinds of changes needed.

If you see some errors in files you haven’t edited, then you might want to remove all of the generated docs and regenerate them.

cd $CHPL_HOME
rm -rf build/doc
make docs

Files that have information about documentation

• chapel/README.devel, how doc/ differs in the release vs. the dev version

• chapel/doc/README.rst, talks about .rst and has a list of the documentation available in .rst

• chapel/doc/rst/developer/bestPractices/buildingdocs.rst, this file

Developers should also consider looking through the files in doc/rst/developer/bestPractices/. Some of these files do not end up linked into the public documentation web pages.