diff --git a/doc/sphinx/source/developer.rst b/doc/sphinx/source/developer.rst index dd8f007..dc5e476 100644 --- a/doc/sphinx/source/developer.rst +++ b/doc/sphinx/source/developer.rst @@ -1,106 +1,108 @@ +.. _dev-doc: + Developer documentation ======================= If you have code contributions you'd like to submit to Tamaas, you are in the right place. This page describes the good practices and workflows to follow to get your code in Tamaas. Documentation ------------- Documentation can be built with ``scons doc``, provided the adequate dependencies are installed. The generated files are in ``build-${build_type}/doc/``, with the C++ API in the ``doxygen/html`` subfolder and the Sphinx documentation in the ``sphinx/html`` subfolder. Use them as reference when developing, most functions and classes in Tamaas have API-level documentation. Writing documentation ~~~~~~~~~~~~~~~~~~~~~ Every new functionality in Tamaas should have *at minimum* API-level documentation. In C++, this is done with `Doxygen-styled comments `_. API-level documentation in Python can be done with `pybind11's docstrings `_. Writing code ------------ To check that your code matches Tamaas' coding convention, please run ``scons lint`` *before* committing. This will check the code style of your changes. It runs ``clang-format``, ``clang-tidy``, ``flake8`` and ``mypy``. .. tip:: Subcommands can be used to run individual linting software: - ``scons clang-format`` - ``scons clang-tidy`` - ``scons flake8`` - ``scons mypy`` .. note:: As redundancy measure, linting also occurs in continuous integration on Gitlab. Review the step artifacts to see which changes are necessary. Running tests ------------- .. warning:: Make sure to run in a virtual environment where Tamaas is installed with ``scons dev``, see the :ref:`faq`. To run tests on your local machine:: scons build_tests=True scons test The ``verbose=True`` build option ensures that test output is verbose as well, useful when writing new parametrized tests. Individual tests can be run with:: pytest build-release/tests/test_westergaard.py Check the output for the lines indicating where the Tamaas python extension and the ``libTamaas`` shared libraries were loaded from. For instance, an editable install of Tamaas should give an output like:: module file: /build-release/python/tamaas/__init__.py wrapper: /build-release/python/tamaas/_tamaas.cpython-311-x86_64-linux-gnu.so libTamaas: static link Git workflow ------------ Please follow the very simple `GitHub flow `_ to submit changes, essentially: 1. Fork the project and create a branch to contain your changes 2. Make your changes 3. Create a merge request 4. Address review changes Commit messages ~~~~~~~~~~~~~~~ Commit messages are a very important trace of changes to the code, and should contain enough context information to understand the motivation for the change. A typical commit message structure should be: .. code-block:: text one-line short description of the change 1 or more paragraphs detailing, for example: - what problem the commit fixes - anything non-trivial the code does - things that had to be researched to fix the issue - other important contextual information There is no limit to a commit message length, and that's a good thing: the more context the better, particularly for new functionality and non-trivial changes (like breaking changes). diff --git a/doc/sphinx/source/overview.rst b/doc/sphinx/source/overview.rst index e2409c3..d3be02d 100644 --- a/doc/sphinx/source/overview.rst +++ b/doc/sphinx/source/overview.rst @@ -1,81 +1,81 @@ Library overview ================ Tamaas is mainly composed of three components: - Random surface generation procedures - Model state objects and operators - Contact solving procedures These parts are meant to be independent as well as inter-operable. The first one provides an interface to several stochastic surface generation algorithms described in :doc:`rough_surfaces`. The second provides an interface to a state object :py:class:`Model ` (and C++ class :cpp:class:`tamaas::Model`) as well as integral operators based on the state object (see :doc:`model`). Finally, the third part provides contact solving routines that make use of the integral operators for performance (see :doc:`contact`). .. _sect-tutorials: Tutorials --------- The following tutorial notebooks can also be used to learn about Tamaas: - Elastic Contact (`live notebook `_, `notebook viewer `_) - Rough Surfaces (`live notebook `__, `notebook viewer `__) Citations --------- Tamaas is the fruit of a research effort. To give proper credit to its creators and the scientists behind the methods it implements, you can use the :py:func:`tamaas.utils.publications` function at the end of your python scripts. This function scans global variables and prints the relevant citations for the different capabilities of Tamaas used. Note that it may miss citations if some objects are not explicitly stored in named variables, so please examine the relevant publications in :doi:`10.21105/joss.02121`. Changelog --------- The changelog can be consulted `here `__. Seeking help ------------ You can ask your questions on `gitlab `_ using this `form `_. If you do not have an account, you can create one `on this page `_. Contribution ------------ Contributions to Tamaas are welcome, whether they are code, bug, or -documentation related. +documentation related. Please have a read at the :ref:`dev-doc`. Code .... Please `fork `_ Tamaas and `submit your patch as a merge request `_. Bug reports ........... You can also contribute to Tamaas by reporting any bugs you find `here `__ if you have an account on `gitlab `__. Please read the :ref:`FAQ ` before posting.