Update Technical Documentation for Python Hatchling Build Method #874

CONTRIBUTING.md

@@ -23,18 +23,12 @@ contribution. For certain changes, such as updating a part of the documentation
 this is not necessary.
 
 We place a lot of importance on code quality, expect to have a good 
-amount of code coverage present and run frequent unit tests. All commits and
-pull requests will be tested with [Travis-ci]. Code coverage is being 
-monitored with [Coveralls].
+amount of code coverage present and run frequent unit tests.
+Code coverage is being monitored with [Coveralls].
 
-Locally you can run unit tests by using [pytest] or [tox]. Running pytest 
-manually is good for running a distinct set of unit tests. For a full test run, 
-tox is preferred since this can run the unit tests against multiple versions of
-python.
+Locally you can run unit tests by using [pytest].
 
 ```bash
-    # Run unit tests for all environments 
-    $ tox
     # No coverage
     $ py.test 
     # Coverage
@@ -53,9 +47,10 @@ feature/<ticketnumber>_description_of_feature
 Feature and bugfix branches should be branched from develop and will be merged 
 back into develop once approved through a pull request.
 
-Every pull request will be run through [Travis-ci]. When providing a pull 
-request, please run the unit tests first and make sure they all pass. Please 
-provide new unit tests to maintain 100% coverage. If you send us a pull request
+All commits and pull requests will be automatically tested using 
+[GitHub Actions workflows]. When providing a pull request, please run 
+the unit tests first and make sure they all pass. Please provide new unit tests
+to maintain 100% coverage. If you send us a pull request
 that doesn't pass all tests, please correct the issue at hand or let us 
 know why it's not working.
 
@@ -65,7 +60,6 @@ know why it's not working.
 [Github page for Atramhasis]: https://github.com/OnroerendErfgoed/atramhasis
 [Github issue]: https://github.com/OnroerendErfgoed/atramhasis/issues
 [development guidelines]: https://atramhasis.readthedocs.io/en/latest/development.html
-[Travis-ci]: https://travis-ci.org/OnroerendErfgoed/atramhasis
 [Coveralls]: https://coveralls.io/r/OnroerendErfgoed/atramhasis
 [pytest]: http://pytest.org
-[tox]: http://tox.readthedocs.org
+[GitHub Actions workflows]: https://github.com/OnroerendErfgoed/atramhasis/actions

README.rst

@@ -5,8 +5,8 @@ Atramhasis
         :target: https://pypi.python.org/pypi/atramhasis
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5801135.svg
         :target: https://doi.org/10.5281/zenodo.5801135
-.. image:: https://app.travis-ci.com/OnroerendErfgoed/atramhasis.svg?branch=develop
-        :target: https://app.travis-ci.com/OnroerendErfgoed/atramhasis 
+.. image:: https://github.com/OnroerendErfgoed/atramhasis/actions/workflows/atramhasis_backend.yaml/badge.svg
+        :target: https://github.com/OnroerendErfgoed/atramhasis/actions/workflows/atramhasis_backend.yaml
 .. image:: https://coveralls.io/repos/github/OnroerendErfgoed/atramhasis/badge.svg?branch=develop
         :target: https://coveralls.io/github/OnroerendErfgoed/atramhasis?branch=develop
 .. image:: https://scrutinizer-ci.com/g/OnroerendErfgoed/atramhasis/badges/quality-score.png?b=develop

docs/source/development.rst

@@ -73,13 +73,13 @@ We recommend installing Atramhasis in a virtual environment.
 
    $ python -m venv atramhasis_dev
    $ . atramhasis_dev/bin/activate
-   # Make sure pip and setuptools are up to date
-   $ pip install --upgrade pip setuptools
+   # Make sure pip and pip-tools are up to date
+   $ pip install --upgrade pip pip-tools
 
 To install a fully working development environment a pip requirements-dev.txt
-file is provided. By passing this file to :command:`pip install -r` all 
-requirements for Atramhasis and development of the software (Sphinx, py.test,
-tox) will be installed.
+file is provided. By passing this file to :command:`pip sync` all
+requirements for Atramhasis and development of the software (Sphinx, py.test)
+will be installed.
 
 The following step will help you get the python development environment up and
 running. If you also need to work on the javascript admin backend, please refer
@@ -88,7 +88,7 @@ to the admin module documentation.
 .. code-block:: bash
 
     # Install dependencies
-    $ pip install -r requirements-dev.txt
+    $ pip-sync requirements-dev.txt
     # Install packages in dev mode
     $ pip install -e .
     # create or update database
@@ -98,7 +98,20 @@ to the admin module documentation.
     # generate first RDF download
     $ dump_rdf development.ini
     # compile the Message Catalog Files
-    $ python setup.py compile_catalog
+    $ pybabel compile --directory 'atramhasis/locale' --domain atramhasis --statistics true
+
+Alternatively to pip-sync, you can also use pip to install the requirements.
+
+.. code-block:: bash
+
+    # Install dependencies
+    $ pip install -r requirements-dev.txt
+    # Install packages in dev mode
+    ...
+
+Note that pip-sync will uninstall all packages that are not listed in the requirements.
+If you have packages in your virtualenv that you want to keep or need, you should
+either reinstall them afterwards or use the pip install command instead of pip-sync.
 
 Once you've executed these steps, you can run a development server. This uses
 the standard pyramid server (`Waitress`_) and should not be used as-is in a
@@ -122,10 +135,10 @@ Confirmed known versions are as followed:
 .. code-block:: bash
 
     $ npm -v
-    8.19.4
+    10.2.4
 
     $ node -v
-    v16.20.2
+    v21.6.2
 
     $ grunt -V
     grunt-cli v1.4.3
@@ -154,7 +167,7 @@ to generate js builds. Builds are carried out through a simple `grunt`_ file:
    $ cd atramhasis/static/admin
    $ grunt -v build
 
-This will create a build a place the resulting files in 
+This will create a build and place the resulting files in
 :file:`atramhasis/static/admin/dist`. The web application can be told to use
 this build by setting `dojo.mode` in :file:`development.ini` to `dist`.
 
@@ -278,48 +291,53 @@ Atramhasis is being developed as open source software by the
 
 Since we place a lot of importance of code quality, we expect to have a good 
 amount of code coverage present and run frequent unit tests. All commits and
-pull requests will be tested with `Travis-ci`_. Code coverage is being 
+pull requests will be tested with Github Workflow Actions tests. Code coverage is being
 monitored with `Coveralls`_.
 
-Locally you can run unit tests by using `pytest`_ or `tox`_. Running pytest 
-manually is good for running a distinct set of unit tests. For a full test run, 
-tox is preferred since this can run the unit tests against multiple versions of
-python.
+Locally you can run unit tests by using `pytest`_.
 
 .. code-block:: bash
 
-    # Run unit tests for all environments 
-    $ tox
     # No coverage
     $ py.test 
     # Coverage
     $ py.test --cov atramhasis --cov-report term-missing
     # Only run a subset of the tests
     $ py.test atramhasis/tests/test_views.py
 
-Every pull request will be run through Travis-ci_. When providing a pull 
+Every pull request will be run through Github Workflow Actions tests. When providing a pull
 request, please run the unit tests first and make sure they all pass. Please 
 provide new unit tests to maintain 100% coverage. If you send us a pull request
 and this build doesn't function, please correct the issue at hand or let us 
 know why it's not working.
 
 Distribution
 ============
+To build a distribution for your project, you can use the `hatchling build` command. This command
+will generate the necessary distribution archives, such as wheels and source distributions.
 
-For building a distribution use the prepare command before the distribution command.
-This will build the dojo code in the static folder.
+In addition to building the Python distribution, the `hatchling build` command will also compile
+the JavaScript code located in the `static` folder. This ensures that all static assets are properly
+built and included in the distribution package.
 
 .. code-block:: bash
 
-    $ python setup.py prepare sdist bdist_wheel
+    $ pip install hatch
+    $ hatch build
+
+Alternatively, you can specify your build as a wheel or as a source distribution (sdist) using the
+`-t` or `--type` parameter.
+
+.. code-block:: bash
 
+    $ hatch build -t wheel
+    $ hatch build -t sdist
 
 .. _Flanders Heritage Agency: https://www.onroerenderfgoed.be
 .. _Github page for Atramhasis: https://github.com/OnroerendErfgoed/atramhasis
-.. _Travis-ci: https://travis-ci.org/OnroerendErfgoed/atramhasis
+.. _GitHub Actions workflows: https://github.com/OnroerendErfgoed/atramhasis/actions
 .. _Coveralls: https://coveralls.io/r/OnroerendErfgoed/atramhasis
 .. _pytest: http://pytest.org
-.. _tox: http://tox.readthedocs.org
 .. _npm: https://www.npmjs.org/
 .. _grunt: http://gruntjs.com
 .. _waitress: http://waitress.readthedocs.org