chpl-venv
============

The Makefile in this third-party directory creates a Python virtualenv and
installs the python packages required by `chpldoc`, `start_test`, `c2chapel`,
and the language server inside it.

`chpldoc` uses several python packages to parse RST files and render them in
the various formats.

To re-install the packages, e.g. to pick up updates to the
sphinxcontrib-chapeldomain package, use this command:

```bash
gmake install-requirements

# or on mac, cygwin:
make install-requirements
```

Python Packages
---------------

The primary packages required by `chpldoc` are: `Sphinx`,
`sphinxcontrib-chapeldomain`, `sphinx-rtd-theme`, and `breathe`. The
dependencies for these packages are listed in the next section.

The primary packages required by `start_test` are: `PyYAML`, `argcomplete`,
`filelock`, `setuptools`, and `junitparser`.

The primary packages required by `c2chapel` are: `pycparser` and `pycparserext`.

The primary package required by both `chpl-language-server` (CLS) and
`chplcheck` is `chapel-py`.  The packages required by `chapel-py` are listed in
`$CHPL_HOME/tools/chapel-py/pyproject.toml`

### Sphinx

Python documentation generator

Used to generate html, pdf, etc documentation from ReStructured Text generated
by `chpldoc`.

**License**: BSD

**Website**: https://pypi.org/project/Sphinx/

### sphinxcontrib-chapeldomain

Sphinx extension that declares the Chapel language domain.

Used with Sphinx to parse Chapel directives in ReStructured Text generated by
`chpldoc`.

**License**: Apache v2.0

**Website**: https://pypi.org/project/sphinxcontrib-chapeldomain/

### sphinx-rtd-theme

ReadTheDocs.org theme for Sphinx

Use with Sphinx as theme for html documentation.

**License**: MIT

**Website**: https://pypi.org/project/sphinx-rtd-theme/

### breathe

Sphinx doxygen renderer

Used with Sphinx to support the compiler developer documentation.

**License**: BSD

**Website**: https://pypi.org/project/breathe/

### PyYAML

A YAML parser and emitter for Python.

**License**: MIT

**Website**: https://pypi.org/project/PyYAML/

### argcomplete

Tab completion of arguments.

Used by `start_test` to enable tab completion.

**License**: Apache v2.0

**Website**: https://pypi.org/project/argcomplete/

### filelock

A platform independent file lock.

Used by `start_test` to make our execution limiter race free, to avoid
timeouts while testing.

**License**: Unlicense

**Website**: https://pypi.org/project/filelock/

### setuptools

Easily download, build, install, upgrade, and uninstall Python packages.

Used by `start_test` to install Arkouda's dependencies.

**License**: MIT

**Website**: https://pypi.org/project/setuptools/

### junitparser

Manipulates JUnit/xUnit Result XML files.

Used by `nightly` to parse the Chapel Language Server tests.

**License**: Apache v2.0

**Website**: https://pypi.org/project/junitparser/

### pycparser

C parser in Python.

Required by c2chapel.

**License**: BSD

**Website**: https://pypi.org/project/pycparser/

### pycparserext

Extensions for pycparser.

Required by c2chapel.

**License**: MIT

**Website**: https://pypi.org/project/pycparserext/

Package Dependencies
--------------------

This section lists additional python packages that are installed in support of
those listed above.

### babel

Internationalization utilies.

A collection of tools for internationalizing Python applications.  Required by
Sphinx.

**License**: BSD

**Website**: https://pypi.org/project/babel/

### Jinja2

A small but fast and easy to use stand-alone template engine written in pure
python.

Required by Sphinx.

**License**: BSD

**Website**: https://pypi.org/project/Jinja2/

### MarkupSafe

Implements a XML/HTML/XHTML Markup safe string for Python

Required by Sphinx.

**License**: BSD

**Website**: https://pypi.org/project/MarkupSafe/

### Pygments

Pygments is a syntax highlighting package written in Python.

Required by Sphinx.

**License**: BSD

**Website**: https://pypi.org/project/Pygments/

### docutils

Python Documentation Utilities

Required by Sphinx, and man page generation.

**License**: public domain, Python, 2-Clause BSD, GPL 3 (see COPYING.txt, also found at http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/COPYING.txt)

**Website**: https://pypi.org/project/docutils/

### urllib3

HTTP library with thread-safe connection pooling, file post, and more.

Required by Sphinx.

**License**: MIT

**Website**: https://pypi.org/project/urllib3/

