Chapel Domain for Sphinx

Chapel domain for Sphinx.

Package documentation is available on readthedocs.org.

Installation

To install:

python3 -m pip install sphinxcontrib-chapeldomain

To install from source on github:

git clone https://github.com/chapel-lang/sphinxcontrib-chapeldomain
cd sphinxcontrib-chapeldomain
python setup.py install

Making Changes

1. Test and commit changes
2. Merge your changes
3. Generate a new PyPI release

Making a Release

1. Go to main page for repo
2. Click “Releases” on right side of screen
3. Click “Draft a new release” button on top of screen
4. For the tag, make a new tag with the new version number
5. You can generate the release notes via the “generate release notes” button, comparing against the most recent release. This will autofill in the details for you

6. Click "Publish release"

   • This will trigger the workflow to push a new release to PyPI, assuming no problems have snuck into our release procedure since the last time it was run

7. Open a PR bumping the version to the next version number so that we're ready for the next change. This should always be the first PR in a new release (otherwise we'll have build issues). This can be done by running the 'bump-version' GitHub Action, which will create the PR for you.

In case of issues, the release pushing job is in .github/workflows/python-publish.yml

You can modify it to try and get things to work. If the issue has something to do with what was pushed to PyPI, you can adjust it to send to https://test.pypi.org/ instead and download from there. You’ll want to remove the bad version from PyPI in that case, which will require access to a user account associated with the repository on PyPI.

Getting Started

This is an example that covers several features of the Chapel domain:

.. chpl:module:: GMP
    :synopsis: multiple precision integer library

.. chpl:record:: BigNum

    multiple precision instances

    .. chpl:method:: proc add(a:BigNum, b:BigNum)

        Add two big ints, ``a`` and ``b``, and store the result in ``this``
        instance.

        :arg a: BigNum to be added
        :type a: BigNum

        :arg BigNum b: BigNum to be added

        :returns: nothing, result is stored in current instance

    .. chpl:itermethod:: iter these() ref

        Arbitrary iterator that returns individual digits of this instance.

        :ytype: reference
        :yields: reference to each individual digit of BigNum