Skip to content

Commit 21ad2a5

Browse files
jorgepilotojorgepiloto
committed
Add usage guidelines
1 parent 7502ec7 commit 21ad2a5

File tree

4 files changed

+219
-2
lines changed

4 files changed

+219
-2
lines changed

‎README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎README.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
PyAnsys library as cookiecutter template
2+
========================================
3+
4+
This repository holds a `cookiecutter`_ template for
5+
creating a Python library. The process is fully interactive and the rendered
6+
project is compliant with the `PyAnsys Developer's guide`_.
7+
8+
9+
Requirements
10+
------------
11+
12+
Before creating your library, you will need to install `cookiecutter`_ via:
13+
14+
.. code:: bash
15+
16+
python -m pip install cookiecutter
17+
18+
19+
How to use
20+
----------
21+
22+
Once you have installed `cookiecutter`_, you can create a new Python library by
23+
calling this template using:
24+
25+
.. code:: bash
26+
27+
cookiecutter gh:pyansys/pyansys-template
28+
29+
Previous command will ask you to introduce different data regarding your new
30+
Python project. Some of these are already pre-defined but you can always change
31+
their value:
32+
33+
- **product_name**: the name of Ansys product (i.e. Product).
34+
- **product_name_slug**: product sanitized name (i.e. product).
35+
- **library_name**: the name of the product library (i.e. Library).
36+
- **library_name_slug**: library named sanitized (i.e. library).
37+
- **project_name_slug**: the project's directory name (i.e. pyproduct-library).
38+
- **pkg_name**: the name of the Python package/library (i.e. ansys-product-library).
39+
- **version**: the version of the package/library (i.e. 0.1.dev0).
40+
- **short_description**: a short description of the purpose/goal of the project.
41+
- **repository_url**: link to the repository where the source code will be hosted.
42+
- **requires_python**: choose the minimum required Python version among 3.7, 3.8, 3.9 or 3.10.
43+
- **build_system**: choose the build system among flit, poetry or setuptools.
44+
- **max_linelength**: maximum number of characters per line in the source code (i.e. 100).
45+
46+
47+
How to contribute
48+
-----------------
49+
50+
For developers, the requirements can be installed via:
51+
52+
.. code:: bash
53+
54+
python -m pip install -r requirements/requirements_dev.txt
55+
56+
The coding style checks and unit tests are executed via `tox`_. Simply execute:
57+
58+
.. code:: bash
59+
60+
tox
61+
62+
and all the environments (style and tests) will be checked.
63+
64+
65+
.. LINKS AND REFERENCES
66+
.. _cookiecutter: https://cookiecutter.readthedocs.io/en/latest/
67+
.. _PyAnsys Developer's guide: https://dev.docs.pyansys.com/
68+
.. _tox: https://tox.wiki/

‎tox.ini‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ basepython =
1818
py38: python3.8
1919
py39: python3.9
2020
py310: python3.10
21-
{style,reformat}: python3
21+
{style}: python3
2222
setenv =
2323
PYTHONUNBUFFERED = yes
2424
keep-output: PYTEST_MARKERS = --keep-baked-projects --basetemp=output

‎{{cookiecutter.project_name_slug}}/README.rst‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,153 @@ Py{{ cookiecutter.product_name }} {{ cookiecutter.library_name }}
22
{{ '=' * (cookiecutter.project_name_slug | length) }}
33

44
{{ cookiecutter.short_description }}
5+
6+
7+
How to install
8+
--------------
9+
10+
At least two installation modes are provided: user and developer.
11+
12+
For users
13+
^^^^^^^^^
14+
15+
In order to install Py{{ cookiecutter.product_name }} {{ cookiecutter.library_name }}, make sure you
16+
have the required build system tool. To do so, run:
17+
18+
.. code:: bash
19+
20+
python -m pip install -U pip {{ cookiecutter.build_system }}
21+
22+
Then, you can simply execute:
23+
24+
{% if cookiecutter.build_system in ["flit", "setuptools"] %}
25+
26+
.. code:: bash
27+
28+
python -m pip install {{ cookiecutter.pkg_name }}
29+
30+
{% elif cookiecutter.build_system == "poetry" %}
31+
32+
.. code:: bash
33+
34+
poetry run python -m pip install {{ cookiecutter.pkg_name }}
35+
36+
{% endif %}
37+
38+
39+
For developers
40+
^^^^^^^^^^^^^^
41+
42+
Installing Py{{ cookiecutter.product_name }} {{ cookiecutter.library_name }} in developer mode allows
43+
you to modify the source and enhance it.
44+
45+
Before contributing to the project, please refer to the `PyAnsys Developer's guide`_. You will
46+
need to follow these steps:
47+
48+
1. Start by cloning this repository:
49+
50+
.. code:: bash
51+
52+
git clone {{ cookiecutter.repository_url }}
53+
54+
2. Create a fresh-clean Python environment and activate it:
55+
56+
.. code:: bash
57+
58+
python -m venv .venv && source venv .venv
59+
60+
3. Make sure you have the latest required build system and testing/CI tools:
61+
62+
.. code:: bash
63+
64+
python -m pip install -U pip {{ cookiecutter.build_system }} tox
65+
66+
4. Install the project in editable mode:
67+
68+
{% if cookiecutter.build_system in ["flit", "setuptools"] %}
69+
70+
.. code:: bash
71+
72+
python -m pip install --editable {{ cookiecutter.pkg_name }}
73+
74+
{% elif cookiecutter.build_system == "poetry" %}
75+
76+
.. code:: bash
77+
78+
poetry run python -m pip install {{ cookiecutter.pkg_name }}
79+
80+
{% endif %}
81+
82+
5. Finally, verify your development installation by running:
83+
84+
.. code:: bash
85+
86+
tox
87+
88+
89+
How to testing
90+
--------------
91+
92+
This project takes advantage of `tox`_. This tool allows to automate common
93+
development tasks (similar to Makefile) but it is oriented towards Python
94+
development.
95+
96+
Using tox
97+
^^^^^^^^^
98+
99+
As Makefile has rules, `tox`_ has environments. In fact, the tool creates its
100+
own virtual environment so anything being tested is isolated from the project in
101+
order to guarantee project's integrity. The following environments commands are provided:
102+
103+
- **tox -e style**: will check for coding style quality.
104+
- **tox -e py3X**: being X the minor version of your Python environment. Checks for unit tests.
105+
- **tox -e py3X-coverage**: checks for unit testing and code coverage.
106+
- **tox -e doc**: checs for documentation building process.
107+
108+
109+
Raw testing
110+
^^^^^^^^^^^
111+
112+
If required, you can always call the style commands (`black`_, `isort`_,
113+
`flake8`_...) or unit testing ones (`pytest`_) from the command line. However,
114+
this does not guarantee that your project is being tested in an isolated
115+
environment, which is the reason why tools like `tox`_ exist.
116+
117+
118+
A note on pre-commit
119+
^^^^^^^^^^^^^^^^^^^^
120+
121+
The style checks take advantage of `pre-commit`_. Developers are not forced but
122+
encouraged to install this tool via:
123+
124+
.. code:: bash
125+
126+
python -m pip install pre-commit && pre-commit install
127+
128+
129+
Documentation
130+
-------------
131+
132+
For building documentation, you can either run the usual rules provided in the
133+
`Sphinx`_ Makefile, such us:
134+
135+
.. code:: bash
136+
137+
make -C doc/ html && your_browser_name doc/html/index.html
138+
139+
However, the recommended way of checking documentation integrity is using:
140+
141+
.. code:: bash
142+
143+
tox -e doc && your_browser_name .tox/doc_out/html/index.html
144+
145+
146+
.. LINKS AND REFERENCES
147+
.. _black: https://github.com/psf/black
148+
.. _flake8: https://flake8.pycqa.org/en/latest/
149+
.. _isort: https://github.com/PyCQA/isort
150+
.. _PyAnsys Developer's guide: https://dev.docs.pyansys.com/
151+
.. _pre-commit: https://pre-commit.com/
152+
.. _pytest: https://docs.pytest.org/en/stable/
153+
.. _Sphinx: https://www.sphinx-doc.org/en/master/
154+
.. _tox: https://tox.wiki/

0 commit comments

Comments
 (0)