<commit_before>***************
Developer Guide
***************

This guide is intended for people who want to contribute
to the code, documentation, and test coverage of the core COMPAS packages:

* :mod:`compas`
* :mod:`compas_blender`
* :mod:`compas_ghpython`
* :mod:`compas_plotters`
* :mod:`compas_rhino`

Note, however, that the general procedure is applicable to all COMPAS package development.


Setup/Installation
==================

To set up a developer environment

1. Fork `the repository <https://github.com/compas-dev/compas>`_ and clone the fork.
2. Create a virtual environment using your tool of choice (e.g. `virtualenv`, `conda`, etc).

   .. code-block:: bash

       conda create -n compas-dev python=3.8 cython --yes
       conda activate compas-dev

3. Install development dependencies:

   .. code-block:: bash

       cd path/to/compas
       pip install -r requirements-dev.txt

4. Make sure all tests pass and the code is free of lint:

   .. code-block:: bash

       invoke lint
       invoke test

5. Create a branch for your contributions.

   .. code-block::

       git branch title-proposed-changes
       git checkout title-proposed-changes

6. Start making changes!


Submitting a PR
===============

Once you are done making changes, you have to submit your contribution through a pull request (PR).
The procedure for submitting a PR is the following.

1. Make sure all tests still pass, the code is free of lint, and the docstrings compile correctly:

   .. code-block:: bash

        invoke lint
        invoke test
        invoke docs

2. Add yourself to ``AUTHORS.md``.
3. Summarize the changes you made in ``CHANGELOG.md``.
4. Commit your changes and push your branch to GitHub.
5. Create a `pull request <https://help.github.com/articles/about-pull-requests/>`_.


Style guide
===========

The command ``invoke lint`` runs the entire codebase through ``flake8``.
As described in the `docs <https://flake8.pycqa.org/en/latest/manpage.html>`_,
``flake8`` includes lint checks provided by the PyFlakes project,
PEP-0008 inspired style checks provided by the PyCodeStyle project,
and McCabe complexity checking provided by the McCabe project.

The list of potential error codes issued by ``flake8`` are available here:
https://flake8.pycqa.org/en/latest/user/error-codes.html

The PEP-0008 style guide is available here:
https://www.python.org/dev/peps/pep-0008/

Note that the maximum line length is set to 180 rather 79 in the ``setup.cfg`` of the repo.


Naming conventions
==================

We (intend to) use the following naming conventions.

1. variables, functions, methods, attributes use "snake_case":
   they are written in lowercase and spaces between words are replaced by underscores.

2. class names use (Upper) "CamelCase":
   The are written in lowercase, with the first letter of each word capitalized
   and spaces between words removed.

3. module or package level variables are in uppercase
   and with spaces between words replaced by underscores.


Quotes
======

Ideally, we would use the following conventions for quotes.

1. Double quotation marks for multiline statements and docstrings.
   For example, ``"""Calculate the sum of two numbers."""``

2. Single quotation marks for strings that are used "as variables".
   For example, ``config['param'] = 1``.

3. Double quotation marks for strings that are meant to be used as text.
   For examples, ``message = "Select one or more points."``


Documentation
=============

The documentation of COMPAS is generated with Sphinx.
This means that code docstrings and general documentation pages
have to be written in RestructuredText.

Each function, method, and class should have a docstring describing its behaviour.
We use ``sphinx.ext.napoleon`` to allow for human-readable docstrings,
and prefer Numpy-style docstring formatting rules.

* https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
* https://numpydoc.readthedocs.io/en/latest/format.html

To include a new function or class in the documentation,
it should be added to the API docstring in ``__init__.py`` of the main package it belongs to.

For example, if you add a function somewhere in the geometry package,
make sure to include it in the docstring of ``compas.geometry.__init__.py``.


Type hints
==========

Type hints should be added to stub files at the public API level
of the main packages (see :ref:`code_structure`).
This allows the type hints to be written using Python 3 style
annotations while maintaining compatibility with Python 2.7 for Rhino/GH.<commit_msg>fix ref to code structure<commit_after>***************
Developer Guide
***************

This guide is intended for people who want to contribute
to the code, documentation, and test coverage of the core COMPAS packages:

* :mod:`compas`
* :mod:`compas_blender`
* :mod:`compas_ghpython`
* :mod:`compas_plotters`
* :mod:`compas_rhino`

Note, however, that the general procedure is applicable to all COMPAS package development.


Setup/Installation
==================

To set up a developer environment

1. Fork `the repository <https://github.com/compas-dev/compas>`_ and clone the fork.
2. Create a virtual environment using your tool of choice (e.g. `virtualenv`, `conda`, etc).

   .. code-block:: bash

       conda create -n compas-dev python=3.8 cython --yes
       conda activate compas-dev

3. Install development dependencies:

   .. code-block:: bash

       cd path/to/compas
       pip install -r requirements-dev.txt

4. Make sure all tests pass and the code is free of lint:

   .. code-block:: bash

       invoke lint
       invoke test

5. Create a branch for your contributions.

   .. code-block::

       git branch title-proposed-changes
       git checkout title-proposed-changes

6. Start making changes!


Submitting a PR
===============

Once you are done making changes, you have to submit your contribution through a pull request (PR).
The procedure for submitting a PR is the following.

1. Make sure all tests still pass, the code is free of lint, and the docstrings compile correctly:

   .. code-block:: bash

        invoke lint
        invoke test
        invoke docs

2. Add yourself to ``AUTHORS.md``.
3. Summarize the changes you made in ``CHANGELOG.md``.
4. Commit your changes and push your branch to GitHub.
5. Create a `pull request <https://help.github.com/articles/about-pull-requests/>`_.


Style guide
===========

The command ``invoke lint`` runs the entire codebase through ``flake8``.
As described in the `docs <https://flake8.pycqa.org/en/latest/manpage.html>`_,
``flake8`` includes lint checks provided by the PyFlakes project,
PEP-0008 inspired style checks provided by the PyCodeStyle project,
and McCabe complexity checking provided by the McCabe project.

The list of potential error codes issued by ``flake8`` are available here:
https://flake8.pycqa.org/en/latest/user/error-codes.html

The PEP-0008 style guide is available here:
https://www.python.org/dev/peps/pep-0008/

Note that the maximum line length is set to 180 rather 79 in the ``setup.cfg`` of the repo.


Naming conventions
==================

We (intend to) use the following naming conventions.

1. variables, functions, methods, attributes use "snake_case":
   they are written in lowercase and spaces between words are replaced by underscores.

2. class names use (Upper) "CamelCase":
   The are written in lowercase, with the first letter of each word capitalized
   and spaces between words removed.

3. module or package level variables are in uppercase
   and with spaces between words replaced by underscores.


Quotes
======

Ideally, we would use the following conventions for quotes.

1. Double quotation marks for multiline statements and docstrings.
   For example, ``"""Calculate the sum of two numbers."""``

2. Single quotation marks for strings that are used "as variables".
   For example, ``config['param'] = 1``.

3. Double quotation marks for strings that are meant to be used as text.
   For examples, ``message = "Select one or more points."``


Documentation
=============

The documentation of COMPAS is generated with Sphinx.
This means that code docstrings and general documentation pages
have to be written in RestructuredText.

Each function, method, and class should have a docstring describing its behaviour.
We use ``sphinx.ext.napoleon`` to allow for human-readable docstrings,
and prefer Numpy-style docstring formatting rules.

* https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
* https://numpydoc.readthedocs.io/en/latest/format.html

To include a new function or class in the documentation,
it should be added to the API docstring in ``__init__.py`` of the main package it belongs to.

For example, if you add a function somewhere in the geometry package,
make sure to include it in the docstring of ``compas.geometry.__init__.py``.


Type hints
==========

Type hints should be added to stub files at the public API level
of the main packages (see :ref:`code-structure`).
This allows the type hints to be written using Python 3 style
annotations while maintaining compatibility with Python 2.7 for Rhino/GH.
{'fraction_non_alphanumeric': 0.10153005464480874, 'fraction_numerical': 0.009836065573770493, 'mean_word_length': 3.9093347639484977, 'pattern_counts': {'":': 4, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 14, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3051149', 'n_tokens_mistral': 2620, 'n_tokens_neox': 2473, 'n_words': 1163}