Skip to content

Commit f5a6fc3

Browse files
jorgepilotojorgepiloto
committed
WIP: structure
1 parent 8576907 commit f5a6fc3

File tree

5 files changed

+175
-7
lines changed

5 files changed

+175
-7
lines changed

‎doc/source/packaging/diagrams/ansys_project_diagram.rst

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.. _high level pyansys structure:
2+
.. graphviz::
3+
:caption: High-level strcuture of a PyAnsys project
4+
:alt: High-level strcuture of a PyAnsys project
5+
:align: center
6+
7+
digraph "sphinx-ext-graphviz" {
8+
size="6,4";
9+
rankdir="LR";
10+
graph [
11+
fontname="Verdana", fontsize="10", color="black", fillcolor="white"
12+
];
13+
node [
14+
fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107"
15+
];
16+
17+
pyansys_project [
18+
label="PyAnsys Project", shape="folder"
19+
];
20+
21+
python_library [
22+
label="Python Library", shape="folder"
23+
];
24+
25+
other_files [
26+
label="Other Files", shape="node"
27+
];
28+
29+
pyansys_project -> python_library;
30+
pyansys_project -> other_files;
31+
32+
}
33+
34+

‎doc/source/packaging/diagrams/python_elements_diagram.rst

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. _python elements diagram:
2+
.. graphviz::
3+
:caption: Differences between Python modules, sub-packages and, packages
4+
:alt: Differences between Python modules, sub-packages and, packages
5+
:align: center
6+
7+
digraph "sphinx-ext-graphviz" {
8+
size="6,4";
9+
rankdir="LR";
10+
graph [
11+
fontname="Verdana", fontsize="10", color="black", fillcolor="white"
12+
];
13+
node [
14+
fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107"
15+
];
16+
17+
package [
18+
label="Package A", shape="folder"
19+
];
20+
21+
sub_package [
22+
label="Sub-Package A", shape="folder"
23+
];
24+
25+
init_file1 [
26+
label="__init__.py", shape="file"
27+
];
28+
29+
init_file2 [
30+
label="__init__.py", shape="file"
31+
];
32+
33+
module_foo [
34+
label="foo.py", shape="file"
35+
];
36+
37+
module_bar [
38+
label="bar.py", shape="file"
39+
];
40+
41+
package -> sub_package;
42+
package -> init_file1;
43+
package -> module_bar;
44+
45+
sub_package -> init_file2;
46+
sub_package -> module_foo;
47+
48+
}
49+
50+

‎doc/source/packaging/diagrams/python_pkg_lib_diagram.rst

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
.. _python pkg lib diagram:
2+
.. graphviz::
3+
:caption: Difference between Python library and package
4+
:alt: Difference between Python library and package
5+
:align: center
6+
7+
digraph "sphinx-ext-graphviz" {
8+
size="6,4";
9+
rankdir="LR";
10+
graph [
11+
fontname="Verdana", fontsize="10", color="black", fillcolor="white"
12+
];
13+
node [
14+
fontname="Verdana", fontsize="10", style="filled", color="black", fillcolor="#ffc107"
15+
];
16+
17+
python_library [
18+
label="Python Library", shape="folder"
19+
];
20+
21+
pkg_A [
22+
label="Package A", shape="folder"
23+
];
24+
25+
pkg_B [
26+
label="Package B", shape="folder"
27+
];
28+
29+
pkg_other [
30+
label="...", shape="folder"
31+
];
32+
33+
34+
python_library -> pkg_A
35+
python_library -> pkg_B
36+
python_library -> pkg_other
37+
38+
}
39+
40+

‎doc/source/packaging/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ model and API.
4141
:maxdepth: 3
4242

4343
templates
44+
structure
4445

4546
.. _gRPC: https://grpc.io/
4647
.. _pythoncom: http://timgolden.me.uk/pywin32-docs/pythoncom.html

‎doc/source/packaging/structure.rst

+50-7
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,23 @@
1-
.. ref_project_structure::
1+
.. _ref_project_structure:
22

33
#################
44
Project Structure
55
#################
66

77
Most of the projects in the PyAnsys ecosystem ship in the form of a Python
8-
package. This is the formal way of distributing Python-based projects.
8+
library with other additional files. All these files form what it is called a
9+
"project". A project can be uploaded to a repository to better track the changes
10+
applied to it. The high-level structure of a PyAnsys project is exposed in
11+
figure :numref:`high level pyansys structure`.
912

10-
The guide presented in this page is compliant with the `Python Packaging
11-
Authority`_ and `PyAnsys`_ recommendations.
13+
.. include:: diagrams/ansys_project_diagram.rst
14+
15+
Python Libraries
16+
================
17+
18+
A Python library is the formal way of distributing Python source code. It allows
19+
to reuse and specify Python code dependencies. The guide presented in this page
20+
is compliant with the `Python Packaging Authority`_ and PyAnsys recommendations.
1221

1322
.. note::
1423

@@ -17,9 +26,43 @@ Authority`_ and `PyAnsys`_ recommendations.
1726
PyAnsys guidelines are built on top of PyPA guidelines.
1827

1928

20-
.. TODO: Explain the difference between Package and Library?
21-
Package: only holds modules
22-
Library: a collection of packages
29+
Scripts, Modules, Sub-packages, and Packages
30+
--------------------------------------------
31+
32+
To understand the structure of a Python Library, it is important to know
33+
the difference between Python scripts, modules, sub-packages, and packages.
34+
Figure :numref:`python elements diagram` provides a graphical interpretation.
35+
36+
* ``Script``: Any Python file with logic source code.
37+
* ``Module``: Any Python script hosted next to an ``__init__.py`` file.
38+
* ``Sub-package``: Any directory containing various Python modules.
39+
* ``Package``: Any directory containing Python modules and sub-packages.
40+
41+
.. include:: diagrams/python_elements_diagram.rst
42+
43+
44+
Differences Between a Python Package and Library
45+
------------------------------------------------
46+
47+
Although both terms are used interchangeably, there is a key difference between
48+
them: a Python package is a collection of Python modules and sub-packages while
49+
a Python Library is a collection of Python packages. Figure :numref:`python pkg
50+
lib diagram` exposes this.
51+
52+
.. include:: diagrams/python_pkg_lib_diagram.rst
53+
54+
55+
Other Files
56+
===========
57+
58+
Additional files can be stored next to a Python Library. These files will not be
59+
included when distributing the library. Most of these files are metadata, tool
60+
configuration files, and CI workflows definitions.
61+
62+
.. tip::
63+
64+
Avoid having lots of additional files. This reduces mainteinance tasks and
65+
provides a clean root project directory.
2366

2467

2568
Required Files for a PyAnsys Project

0 commit comments

Comments
 (0)