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.

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:

Linking within and between files

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

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

Here is a reference to the `Chapel Developers`_ URL later in the .rst file.

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 current sidebar displayed on https://chapel-lang.org/docs/.

There is a strong correlation between the side bar of https://chapel-lang.org/docs/ 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 document name in the sidebar of https://chapel-lang.org/docs/, the second column shows the source files in the repository, and the last column indicates the sub heading the file is under.

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.rst

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–> Compiler 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.