Skip to content

Commit 9023620

Browse files
jorgepilotoPipKatakaszynski
authored
Better Package Style chapter layout (#71)
* New Package Style layout * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * Enable graphviz and numrefs * WIP: structure * Unify Python library diagrams * Fix library typo Co-authored-by: Kathy Pippert <[email protected]> * Complete diagram * Document doc/ dir structure * Document src/ dir structure * Document tests/ dir structure * Document LICENSE file * Improve doc/ directory explanations * Document Naming Convention section * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * Document README.rst section * Document pyproject.toml and setup.py sections * Add build-systems.rst section * Add sphinx-tabs requiremnt * Fix setuptools link * Apply code suggestions * Add build-systems.rst diagrams * Add build system section * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * Enable Sphinx autolabeling * Fix cross references * Fix setuptools tab * Rename diagrams -> diag * Fix sphinx-tabs version * Apply style * Rename resources -> code * Fix cross references * Ignore duplicated autosectionlabel references * Add diagrams dependencies in CI deps * Apply suggestions from code review Co-authored-by: Alex Kaszynski <[email protected]> * Apply suggestions from code review Co-authored-by: Alex Kaszynski <[email protected]> * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> * Apply suggestions from code review Co-authored-by: Kathy Pippert <[email protected]> Co-authored-by: Kathy Pippert <[email protected]> Co-authored-by: Alex Kaszynski <[email protected]>
1 parent 6768490 commit 9023620

37 files changed

+1157
-642
lines changed

‎.github/workflows/ci-build.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@ jobs:
3838
with:
3939
python-version: 3.8
4040

41+
- name: Install diagrams dependencies
42+
run: |
43+
sudo apt-get update
44+
sudo apt-get install nodejs npm graphviz
45+
npm install -g @mermaid-js/mermaid-cli
46+
4147
- name: Build HTML Documentation
4248
run: |
4349
pip install -r requirements_docs.txt --disable-pip-version-check

‎.github/workflows/nightly-build.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,12 @@ jobs:
1818
with:
1919
python-version: 3.8
2020

21+
- name: Install mermaid-cli
22+
run: |
23+
sudo apt-get update
24+
sudo apt-get install nodejs npm graphviz
25+
npm install -g @mermaid-js/mermaid-cli
26+
2127
- name: Build HTML Documentation
2228
run: |
2329
pip install -r requirements_docs.txt --disable-pip-version-check

‎doc/source/conf.py

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,14 @@
3030
"sphinx_copybutton",
3131
"sphinx_toolbox.collapse",
3232
"sphinx.ext.autodoc",
33+
"sphinx.ext.autosectionlabel",
3334
"sphinx.ext.autosummary",
35+
"sphinx.ext.graphviz",
3436
"sphinx.ext.intersphinx",
3537
"sphinx.ext.napoleon",
3638
"sphinx.ext.todo",
39+
"sphinxcontrib.mermaid",
40+
"sphinx_tabs.tabs",
3741
]
3842

3943
# Intersphinx mapping
@@ -89,3 +93,22 @@
8993
# author, 'ansys.mapdl.core', 'Pythonic interface to MAPDL using gRPC',
9094
# 'Engineering Software'),
9195
# ]
96+
97+
# Include numerical references for the figures
98+
numfig = True
99+
100+
# Do not include the following patterns as documentation source files.
101+
# See issue: https://github.com/sphinx-doc/sphinx/issues/1668
102+
exclude_patterns = ["packaging/diag/*", "packaging/code/*"]
103+
104+
# Fix excessive margins in mermaid output.
105+
# See issue: https://github.com/mermaid-js/mermaid/issues/1800#issuecomment-741617143
106+
mermaid_output_format = "png"
107+
mermaid_params = ["--width", "2000"]
108+
109+
# Generate section labels up to three levels deep
110+
autosectionlabel_maxdepth = 3
111+
112+
# TODO: warning suppression is temporary till https://github.com/pyansys/dev-guide/issues/64
113+
# gets fully implemented.
114+
suppress_warnings = ["autosectionlabel.*"]

‎doc/source/guidelines/dev_practices.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,11 +84,11 @@ changes any given branch is introducing before looking at the code.
8484
- ``doc/``: for any changes only pertaining to documentation
8585
- ``no-ci/``: for low-impact activity that should not trigger the CI
8686
routines
87-
- ``testing/``: improvements or changes to testing
88-
- ``release/``: releases (see below)
87+
- ``testing/``: Improvements or changes to testing
88+
- ``release/``: Releases (see below)
8989

90-
Testing
91-
~~~~~~~
90+
Unit Testing
91+
~~~~~~~~~~~~
9292
When making changes, periodically test locally before creating a PR.
9393
Because the following tests are executed after any commit or PR, we
9494
ask that you perform the following procedure locally to track down

‎doc/source/guidelines/test_practices.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,8 @@ and a Python wrapping:
245245
command : str
246246
Command to run on the remote server.
247247
248+
"""
249+
248250
Your example test would be:
249251

250252
.. code:: python
@@ -282,8 +284,8 @@ Testing Framework
282284
For consistency, PyAnsys tools and libraries should use either the `unittest
283285
<https://docs.python.org/3/library/unittest.html>`_ or `pytest
284286
<https://docs.pytest.org/>`_ frameworks for unit testing. As described in
285-
:ref:`repo_dir_struct`, unit tests should be placed into the ``tests``
286-
directory in the root directory of the library::
287+
:ref:`Required Files for a PyAnsys Project`, unit tests should be placed in the ``tests``
288+
directory in the library's root directory::
287289

288290
tests/
289291
test_basic.py

‎doc/source/overview/administration.rst

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -43,14 +43,14 @@ description, or branch protection management.
4343

4444
Each repository is expected to follow this minimum set of standards:
4545

46-
- Minimum code standards following PEP8. See :ref:`best_practices`.
47-
- CI/CD using GitHub actions or Azure DevOps to enforce coding standards. See :ref:`ci_cd`.
48-
- Publicly hosted documentation detailing API with examples. See
46+
- PEP8 code standards. See :ref:`best_practices`.
47+
- CI/CD using GitHub actions or Azure DevOps to enforce coding standards.
48+
- Publicly hosted documentation describing the API and providing examples. See
4949
:ref:`api_documentation`.
50-
- Unit testing with at least 80% test coverage. See :ref:`ci_cd`.
50+
- Unit testing with at least 80% test coverage.
5151
- Infrastructure in place to deploy the library as a package on `PyPi
52-
<https://pypi.org/>`_. See :ref:`packaging`.
53-
- Proper license file and author. See :ref:`setup_file` and :ref:`license_file`.
52+
<https://pypi.org/>`_. See :ref:`Packaging Style`.
53+
- Proper license file and author. See :ref:`The \`\`setup.py\`\` File` and :ref:`The \`\`LICENSE\`\` File`.
5454

5555

5656
Release Procedures and Versioning

‎doc/source/overview/contributing.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ to :ref:`branch_naming` when you are ready to create a pull request.
136136
Licensing
137137
=========
138138
All contributed code will be licensed under the MIT License. For more information, see
139-
:ref:`license_file`. The ``LICENSE`` file containing the MIT License must be included in
139+
:ref:`The \`\`LICENSE\`\` File`. The ``LICENSE`` file containing the MIT License must be included in
140140
the root directory of a PyAnsys repository.
141141

142142
If you did not write the code that you are contributing yourself, it is your

‎doc/source/packaging/build-systems.rst

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
.. _ref_build_system:
2+
3+
############
4+
Build System
5+
############
6+
7+
The build system is a fundamental tool for packaging Python
8+
libraries. It generates distribution files that can be shared with
9+
users and developers.
10+
11+
12+
Artifacts
13+
=========
14+
15+
The build system allows maintainers to generate artifacts for their Python
16+
libraries. Here, `artifacts` refers to both wheel and source files:
17+
18+
- ``Wheel files`` have the ``*.whl`` file extension.
19+
- ``Source files`` have the ``*.tar.gz`` or ``*.zip`` extension.
20+
21+
These are the files to upload to `PyPI`_ when releasing a new version of a
22+
PyAnsys project.
23+
24+
.. warning::
25+
26+
Not all files are included by default in the source distribution. A
27+
`MANIFEST.in`_ is required at the root of the project to specify additional
28+
files.
29+
30+
31+
The interaction between the maintainer and the build system is performed using a
32+
build system tool. This tool provides both a frontend and a backend. The maintainers
33+
trigger the frontend, which then calls the backend to read the
34+
project directory and generate the artifacts, as :numref:`build system diag` shows.
35+
36+
.. include:: diag/build_system_diag.rst
37+
38+
39+
PEP 517 and PEP 518
40+
===================
41+
42+
For a long time, the ``setup.py`` file was the only way of specifying the
43+
project structure, metadata, and installation workflow that `pip`_ was to follow.
44+
However, having to execute a Python file when installing a Python package
45+
introduced the following problems:
46+
47+
- It was not possible to know which dependencies required the ``setup.py`` file
48+
to be properly executed.
49+
50+
- The default Python package installer, `pip`_, expected `setuptools`_ to be the
51+
default build system tool, excluding others like `flit`_ and `poetry`_.
52+
53+
These problems led to the acceptance of `PEP 517`_ and `PEP 518`_.
54+
55+
56+
PEP 517
57+
-------
58+
59+
`PEP 517`_ allows Python developers to specify the build backend tool for
60+
generating artifacts. The previous :numref:`build system diag` diagram shows the
61+
most popular backends:
62+
63+
- `Setuptools`_ , while very popular, lacks the ability to declare build time dependencies
64+
and is difficult to extend.
65+
- `Flit`_ is a lightweight build system tool for Python.
66+
- `Poetry`_ focuses on dependency management and environment isolation.
67+
68+
`PEP 517` introduced the ``build-backend`` key inside the
69+
``[build-system]`` table in the ``pyproject.toml``.
70+
71+
72+
PEP 518
73+
-------
74+
75+
In addition to the ``setup.py`` file, `PEP 518`_ includes a project file named
76+
``pyproject.toml``. The main goal of this file is to specify build time dependencies.
77+
However, some build system tools like `flit`_ or `poetry`_ are able to specify all
78+
project metadata inside the ``pyproject.toml`` file and eliminate usage of the
79+
``setup.py`` file.
80+
81+
To specify the build time requirements, the ``[build-system]`` table must be
82+
declared in the ``pyproject.toml`` file. Within it, the ``requires`` key is
83+
assigned to a list of strings, which are the build time
84+
requirements.
85+
86+
The combination of `PEP 517`_ and `PEP 518`_ leads to the following syntax in a
87+
``pyproject.toml`` file:
88+
89+
.. code:: toml
90+
91+
[build-system]
92+
requires = ["flit"] # Defined by PEP 518
93+
build-backend = "flit_core.api" # Defined by PEP 517
94+
95+
96+
Build Backend Tools
97+
===================
98+
99+
This section lists some of the most popular build systems in the
100+
Python ecosystem. Although all of them achieve the same goal, there are a few
101+
differences regarding their capabilities and the way of specifying project
102+
metadata.
103+
104+
.. TODO: Include links to each build system allowed metadata fields
105+
106+
Setuptools
107+
----------
108+
109+
`Setuptools`_ has been a part of the Python ecosystem for a long time. Unless
110+
you require high control over your project's installation steps, you should use
111+
`flit`_ or `poetry`_.
112+
113+
If you do not need a dynamic installation process, you can consider using a
114+
``setup.cfg`` file. However, the ``setup.py`` file is still required. The ``setup.cfg`` file
115+
should have a call to the ``setup()`` function to act as the entry point of the
116+
build backend system.
117+
118+
All of these `setuptools metadata fields`_ are valid and must be
119+
specified either in the ``setup.py`` or ``setup.cfg`` file.
120+
121+
122+
Flit
123+
----
124+
125+
Flit is a modern and lightweight build system that requires developers
126+
to manage virtual environments on their own. Developers must:
127+
128+
* Create a virtual environment and activate it.
129+
* Install the package in editable mode.
130+
131+
Flit is the default tool for creating a new ``pyansys`` project when using the
132+
`ansys-templates tool`_.
133+
134+
The ``[project]`` section specifies the project's metadata and required
135+
dependencies. For more information, see `flit pyproject.toml
136+
guidelines`_.
137+
138+
139+
Poetry
140+
------
141+
142+
Because of its ``poetry.lock`` file, Poetry provides strong dependency pinning. When
143+
installing a package, poetry creates a virtual environment, thus ensuring an isolated
144+
package development environment.
145+
146+
Nevertheless, it is possible to make Poetry ignore the ``poetry.lock`` file with:
147+
148+
.. code:: bash
149+
150+
poetry config virtualenvs.create false --local
151+
152+
Using `poetry`_ is popular because it:
153+
154+
* Supports pinning dependency versions via a ``poetry.lock`` file that can be
155+
used for testing and CI
156+
* Allows downstream packages to still consume a loose dependency specification
157+
* Integrates with `dependabot`_ to update the pinned version
158+
159+
The ``[tool.poetry]`` section contains metadata and defines project
160+
dependencies. For more information, see `poetry pyproject.toml documentation`_.
161+
162+
163+
.. _MANIFEST.in: https://packaging.python.org/en/latest/guides/using-manifest-in/
164+
.. _PyPI: https://pypi.org/
165+
.. _pip:
166+
.. _flit: https://flit.pypa.io/en/latest/
167+
.. _poetry: https://python-poetry.org/
168+
.. _poetry pyproject.toml documentation: https://python-poetry.org/docs/pyproject/
169+
.. _setuptools: https://pypi.org/project/setuptools/
170+
.. _setuptools metadata fields: https://setuptools.pypa.io/en/latest/userguide/declarative_config.html#declarative-config
171+
.. _flit pyproject.toml guidelines: https://flit.readthedocs.io/en/latest/pyproject_toml.html
172+
.. _dependabot: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates
173+
.. _ansys-templates tool: https://github.com/pyansys/ansys-templates

‎doc/source/packaging/ci_cd.rst

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎doc/source/packaging/code/license_mit_code.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. code:: text
2+
3+
MIT License
4+
5+
Copyright (c) <YEAR> ANSYS, Inc. All rights reserved.
6+
7+
Permission is hereby granted, free of charge, to any person obtaining a copy
8+
of this software and associated documentation files (the “Software”), to
9+
deal in the Software without restriction, including without limitation the
10+
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
11+
sell copies of the Software, and to permit persons to whom the Software is
12+
furnished to do so, subject to the following conditions:
13+
14+
The above copyright notice and this permission notice shall be included in
15+
all copies or substantial portions of the Software.
16+
17+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
23+
IN THE SOFTWARE.

‎doc/source/packaging/code/pyproject_code.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. tabs::
2+
3+
.. tab:: setuptools
4+
5+
.. include:: code/pyproject_setuptools_code.rst
6+
7+
.. tab:: flit
8+
9+
.. include:: code/pyproject_flit_code.rst
10+
11+
.. tab:: poetry
12+
13+
.. include:: code/pyproject_poetry_code.rst

0 commit comments

Comments
 (0)