Skip to content

Commit 107226d

Browse files
akaszynskiakaszynski
committed
init commit
0 parents  commit 107226d

14 files changed

+553
-0
lines changed

‎.gitignore

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Compiled source #
2+
###################
3+
*.pyc
4+
5+
# packages
6+
dist/*
7+
8+
# Pip generated folders #
9+
#########################
10+
*.egg-info/
11+
12+
13+
build/*
14+
doc/build/

‎README.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
2+
3+
4+
5+
PyAnsys Package Basic Structure
6+
-------------------------------
7+
8+
ansys/<product>/<service>/my_module.py
9+
ansys/<product>/<service>/my_other_module.py
10+
ansys/<product>/<service>/__init__.py
11+
README.rst
12+
LICENSE (use Ansys license file in this repo)
13+
setup.py
14+
requirements.txt
15+
docs/conf.py
16+
docs/index.rst
17+
tests/test_basic.py
18+
tests/test_advanced.py
19+
.github/workflows/ci.yml
20+
21+
This contains a `README.rst` containing
22+
- How to install...
23+
24+
25+
Unit Testing
26+
- <you know the drill>
27+
- Will probably require your application/server to be packaged in a
28+
way that lets you consume it from public infrastructure.
29+
30+
Workflows
31+
- Test CI online
32+
- Deploy package automagically
33+
34+
Setup File
35+
- Defines what the "package is"
36+
37+
<Setup File>
38+
39+
40+
Python Modules
41+
- Non-proprietary source.
42+
- Exposes server functionality pythonically.
43+
44+
45+
Documentation Directory `doc`
46+
- Use `pyansys-sphinx-theme <https://sphinxdocs.pyansys.com/>`_

‎doc/Makefile

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = source
8+
BUILDDIR = build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
20+
21+
22+
# customized clean due to examples gallery
23+
clean:
24+
rm -rf build

‎doc/make.bat

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎doc/source/api/pyansys_sphinx_theme.samples.Complex.abs.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
pyansys\_sphinx\_theme.samples.Complex.abs
2+
==========================================
3+
4+
.. currentmodule:: pyansys_sphinx_theme.samples
5+
6+
.. autoproperty:: Complex.abs

‎doc/source/api/pyansys_sphinx_theme.samples.Complex.imag.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
pyansys\_sphinx\_theme.samples.Complex.imag
2+
===========================================
3+
4+
.. currentmodule:: pyansys_sphinx_theme.samples
5+
6+
.. autoproperty:: Complex.imag

‎doc/source/api/pyansys_sphinx_theme.samples.Complex.real.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
pyansys\_sphinx\_theme.samples.Complex.real
2+
===========================================
3+
4+
.. currentmodule:: pyansys_sphinx_theme.samples
5+
6+
.. autoproperty:: Complex.real

‎doc/source/class_documentation.rst

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
***************************
2+
Generate APIs Documentation
3+
***************************
4+
5+
User Guide Documentation Method
6+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7+
8+
There are two main ways of documenting a class using Sphinx. The
9+
first approach is to detail its usage via a "User Guide", or manually
10+
created example designed to be read within documentation. This
11+
approach works when demonstrating the usage of a class. For example,
12+
using the ``.. code:: python`` directive:
13+
14+
.. code::
15+
16+
Initialize ``my_module.MyClass`` with initial parameters. These
17+
parameters are automatically assigned to the class.
18+
19+
.. code:: python
20+
21+
>>> from my_module import MyClass
22+
>>> my_obj = MyClass(parm1='apple', parm2='orange')
23+
>>> my_obj.parm1
24+
'apple'
25+
26+
Initialize ``my_module.MyClass`` with initial parameters. These
27+
parameters are automatically assigned to the class.
28+
29+
.. code:: python
30+
31+
>>> from my_module import MyClass
32+
>>> my_obj = MyClass(parm1='apple', parm2='orange')
33+
>>> my_obj.parm1
34+
'apple'
35+
36+
37+
38+
Autoclass Directive
39+
~~~~~~~~~~~~~~~~~~~
40+
41+
The "user guide" approach works for explaining the "why" and "how" of a class. As
42+
for the "what" of a class, you can describe the API automatically
43+
using the ``autoclass`` directive:
44+
45+
46+
.. code::
47+
48+
.. autoclass:: pyansys_sphinx_theme.samples.ExampleClass
49+
:members:
50+
51+
52+
.. autoclass:: pyansys_sphinx_theme.samples.ExampleClass
53+
:members:
54+
55+
56+
57+
Autosummary Directive
58+
~~~~~~~~~~~~~~~~~~~~~
59+
Simple classes can be easily represented using the ``autoclass``
60+
directive, but more complex classes with many methods should be
61+
documented via the ``autosummary`` directive. For example,
62+
63+
.. code::
64+
65+
.. autoclass:: pyansys_sphinx_theme.samples.Complex
66+
67+
.. autosummary::
68+
:toctree: api/
69+
70+
pyansys_sphinx_theme.samples.Complex.real
71+
pyansys_sphinx_theme.samples.Complex.imag
72+
pyansys_sphinx_theme.samples.Complex.abs
73+
74+
75+
Will generate the following documentation:
76+
77+
.. autoclass:: pyansys_sphinx_theme.samples.Complex
78+
79+
80+
.. autosummary::
81+
:toctree: api/
82+
83+
pyansys_sphinx_theme.samples.Complex.real
84+
pyansys_sphinx_theme.samples.Complex.imag
85+
pyansys_sphinx_theme.samples.Complex.abs
86+
87+
88+
Note how each method or attribute has its own page.

‎doc/source/coding_style.rst

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
********************************
2+
Coding Style and Best Practices
3+
********************************
4+
.. note::
5+
Until we have a site up for our best practices and coding style,
6+
the sphinx documentation site will host the coding style as well.
7+
8+
This page describes coding best practices applicable to the `pyansys
9+
<https://pypi.org/project/pyansys/>`_ project. The purpose of this
10+
page is not to repeat coding style documentation, but rathers to state
11+
the approach used by the pyansys project when there are any
12+
delineations, clarifications, or additional procedures above and
13+
beyond `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
14+
15+
For example, deprecation best practices are outlined in a `Stack
16+
Overflow Answer <https://stackoverflow.com/questions/2536307>`_ and
17+
there's even a `Deprecation library
18+
<https://deprecation.readthedocs.io/>`_ but there is no official
19+
guidance regarding deprecating features in an API within Python. This
20+
document seeks to clarify this issue and others.
21+
22+
Aside from pyansys specific directives, the best coding practice is to simply
23+
follow established guidelines from `PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
24+
25+
26+
Deprecation Best-Practice
27+
-------------------------
28+
Whenever a method, class, or function is deprecated, we must provide
29+
an old method that calls the new method and raises a warning, or raise
30+
an ``AttributeError`` if the method has been removed
31+
altogether. Provide a `Sphinx Deprecated Directive
32+
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated>`_
33+
in the docstring of the older method and link to the newer method.
34+
35+
This way, when API changes are made we give the user a chance to
36+
change theirs too or at least be notified when it changes. Otherwise,
37+
they'll simply stop upgrading, or worse, using our API due to
38+
stability concerns. For this reason, it's best to use a warning first
39+
and then using an error after a minor release or two.
40+
41+
42+
.. code:: python
43+
44+
class FieldAnalysis2D():
45+
"""Class docstring"""
46+
47+
def assignmaterial(self, obj, mat):
48+
"""Assign a material to one or more objects.
49+
50+
.. deprecated:: 0.4.0
51+
Use :func:`FieldAnalysis2D.assign_material` instead.
52+
53+
"""
54+
# one of the following:
55+
56+
# raise a DeprecationWarning. User won't have to change anything
57+
warnings.warn('assignmaterial is deprecated. Please use assign_material instead',
58+
DeprecationWarning)
59+
self.assign_material(obj, mat)
60+
61+
# or raise an AttributeError (could also make a custom DeprecationError)
62+
raise AttributeError('assignmaterial is deprecated. Please use assign_material instead')
63+
64+
def assign_material(self, obj, mat):
65+
"""Assign a material to one or more objects.
66+
...
67+
68+
69+
If a method is outright removed, there's no reason to provide a link
70+
to the old method, and we should simply raise an ``AttributeError``
71+
should this be part of a class, or simply an ``Exception``. For
72+
example:
73+
74+
.. code:: python
75+
76+
def hello_world():
77+
"""Print ``"hello_world"``
78+
79+
.. deprecated:: 0.4.0
80+
This function has been deprecated.
81+
82+
"""
83+
raise Exception('`my_function` has been deprecated')
84+
85+
Alternatively, you can create a custom ``DepricationError`` since
86+
there is no built-in depreciation error within Python.
87+
88+
.. code:: python
89+
90+
class DeprecationError(RuntimeError):
91+
"""Used for depreciated methods and functions."""
92+
93+
def __init__(self, message='This feature has been depreciated'):
94+
"""Empty init."""
95+
RuntimeError.__init__(self, message)
96+
97+
Then simply use that inplace of ``Exception``
98+
99+
.. code:: python
100+
101+
def hello_world():
102+
"""Print ``"hello_world"``
103+
104+
.. deprecated:: 0.4.0
105+
This function has been deprecated.
106+
107+
"""
108+
raise DeprecationError('`my_function` has been deprecated')
109+
110+
111+
Notes Regarding Semantic Versioning and API Changes
112+
---------------------------------------------------
113+
According to `Semantic Versioning <https://semver.org/>`_, you should
114+
increment the MAJOR version when you make incompatible changes.
115+
However, adding or eliminating methods should not be considered
116+
incompatible changes to a code base, but rather incremental changes
117+
what are backwards compatible (to a degree). Therefore, whenever a
118+
method or feature is added, changed, or removed, the minor version
119+
should be bumped.
120+
121+
To avoid constantly bumping the minor version, one approach to for
122+
source-control branching is to create release branches where only
123+
patch fixes are pushed to, and API changes occur between minor
124+
releases. See `Trunk Based Development
125+
<https://trunkbaseddevelopment.com/>`_. In summary, the mainline
126+
branch (commonly named ``main`` or ``master`` must be already read to
127+
release, and developers should create release branches to maintain at
128+
least of one prior minor version.
129+
130+
The reason behind this is if a user wants to use API 0.4.0 instead of
131+
0.5.0 due to some pressing deadline where they want to avoid a code
132+
refactor, the maintainers of the API can back-port a bug-fix via ``git
133+
cherry-pick <COMMIT-HASH>``. This way users are given some time to
134+
update any projects dependent on the API while still being treated as
135+
"first-class" users. Note that due to the complexity of maintaining
136+
multiple "release branches" in a repository, the number of active
137+
release branches should be between one and three.

0 commit comments

Comments
 (0)