Skip to content

Commit 60e57cf

Browse files
AlejandroFernandezLucesAlejandroFernandezLuces
committed
doc: Add docs
1 parent 67a1971 commit 60e57cf

File tree

14 files changed

+512
-4
lines changed

14 files changed

+512
-4
lines changed

‎.gitignore‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,4 +40,8 @@ dist/
4040
config.yaml
4141

4242
# Do not ignore config.yaml in the configs/ directory
43-
!configs/config.yaml
43+
!configs/config.yaml
44+
45+
# Docs
46+
doc/_build/
47+
doc/source/api/

‎AUTHORS‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# This is the list of ansys-tools-visualization-interface's significant contributors.
1+
# This is the list of allie-flowkit-python's significant contributors.
22
#
33
# This file does not necessarily list everyone who has contributed code.
44
#

‎doc/ANSYS/accept.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
(?i)Ansys
2+
pytest

‎doc/ANSYS/reject.txt‎

Whitespace-only changes.

‎doc/Makefile‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS = -j auto -W --color
6+
SPHINXBUILD = sphinx-build
7+
APIDIR = api
8+
EXAMPLESDIR = examples
9+
SOURCEDIR = source
10+
BUILDDIR = _build
11+
12+
# Put it first so that "make" without argument is like "make help".
13+
help:
14+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
15+
16+
.PHONY: help Makefile
17+
18+
# Catch-all target: route all unknown targets to Sphinx using the new
19+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
20+
%: Makefile
21+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
22+
23+
# Customized clean due to examples gallery
24+
clean:
25+
rm -rf $(BUILDDIR)/*
26+
find . -type d -name $(APIDIR) -exec rm -rf {} +
27+
find . -type d -name $(EXAMPLESDIR) -exec rm -rf {} +
28+
29+
# Create PDF
30+
pdf:
31+
@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
32+
cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
33+
34+
# Build HTML files and generate examples as .py files
35+
html:
36+
pip uninstall vtk -y
37+
pip install --extra-index-url https://wheels.vtk.org vtk-osmesa
38+
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/make.bat‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
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+
if "%SPHINXOPTS%" == "" (
11+
set SPHINXOPTS=-j auto -W --color
12+
)
13+
set SOURCEDIR=source
14+
set APIDIR=api
15+
set EXAMPLESDIR=examples
16+
set BUILDDIR=_build
17+
18+
if "%1" == "" goto help
19+
if "%1" == "clean" goto clean
20+
if "%1" == "pdf" goto pdf
21+
if "%1" == "html" goto html
22+
23+
%SPHINXBUILD% >NUL 2>NUL
24+
if errorlevel 9009 (
25+
echo.
26+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
27+
echo.installed, then set the SPHINXBUILD environment variable to point
28+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
29+
echo.may add the Sphinx directory to PATH.
30+
echo.
31+
echo.If you don't have Sphinx installed, grab it from
32+
echo.http://sphinx-doc.org/
33+
exit /b 1
34+
)
35+
36+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
37+
goto end
38+
39+
:html
40+
%SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
41+
goto end
42+
43+
:help
44+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
45+
goto end
46+
47+
:pdf
48+
%SPHINXBUILD% -M latex %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
49+
cd "%BUILDDIR%\latex"
50+
for %%f in (*.tex) do (
51+
pdflatex "%%f" --interaction=nonstopmode)
52+
if NOT EXIST allie-flowkit-python.pdf (
53+
Echo "no pdf generated!"
54+
exit /b 1)
55+
Echo "pdf generated!"
56+
goto end
57+
58+
:clean
59+
rmdir /s /q %BUILDDIR% > /NUL 2>&1
60+
for /d /r %SOURCEDIR% %%d in (%APIDIR%, %EXAMPLESDIR%) do @if exist "%%d" rmdir /s /q "%%d"
61+
goto end
62+
63+
:end
64+
popd

‎doc/source/conf.py‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
"""Sphinx documentation configuration file."""
2+
3+
from datetime import datetime
4+
import os
5+
from pathlib import Path
6+
7+
from allie.flowkit import __version__
8+
from ansys_sphinx_theme import (
9+
ansys_favicon,
10+
ansys_logo_white,
11+
ansys_logo_white_cropped,
12+
get_autoapi_templates_dir_relative_path,
13+
get_version_match,
14+
latex,
15+
pyansys_logo_black,
16+
watermark,
17+
)
18+
from sphinx.builders.latex import LaTeXBuilder
19+
20+
LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
21+
22+
# Project information
23+
project = "allie-flowkit-python"
24+
copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
25+
author = "ANSYS, Inc."
26+
release = version = __version__
27+
cname = os.getenv("DOCUMENTATION_CNAME", default="allie-flowkit-python.docs.pyansys.com")
28+
switcher_version = get_version_match(__version__)
29+
30+
# Select desired logo, theme, and declare the html title
31+
html_logo = pyansys_logo_black
32+
html_theme = "ansys_sphinx_theme"
33+
html_short_title = html_title = "Allie Flowkit Python"
34+
html_baseurl = f"https://{cname}/version/stable"
35+
36+
# specify the location of your github repo
37+
html_context = {
38+
"github_user": "ansys",
39+
"github_repo": "allie-flowkit-python",
40+
"github_version": "main",
41+
"doc_path": "doc/source",
42+
}
43+
html_theme_options = {
44+
"switcher": {
45+
"json_url": f"https://{cname}/versions.json",
46+
"version_match": switcher_version,
47+
},
48+
"check_switcher": False,
49+
"github_url": "https://github.com/ansys/allie-flowkit-python",
50+
"show_prev_next": False,
51+
"show_breadcrumbs": True,
52+
"collapse_navigation": True,
53+
"use_edit_page_button": True,
54+
"additional_breadcrumbs": [
55+
("PyAnsys", "https://docs.pyansys.com/"),
56+
],
57+
"icon_links": [
58+
{
59+
"name": "Support",
60+
"url": "https://github.com/ansys/allie-flowkit-python/discussions",
61+
"icon": "fa fa-comment fa-fw",
62+
},
63+
{
64+
"name": "Download documentation in PDF",
65+
"url": f"https://{cname}/version/{switcher_version}/_static/assets/download/allie-flowkit-python.pdf", # noqa: E501
66+
"icon": "fa fa-file-pdf fa-fw",
67+
},
68+
]
69+
}
70+
71+
# Sphinx extensions
72+
extensions = [
73+
"sphinx.ext.intersphinx",
74+
"sphinx_copybutton",
75+
"sphinx_design",
76+
"sphinx_jinja",
77+
"autoapi.extension",
78+
"numpydoc",
79+
]
80+
81+
nbsphinx_execute = "always"
82+
sphinx_gallery_conf = {
83+
# path to your examples scripts
84+
"examples_dirs": ["../../examples"],
85+
# path where to save gallery generated examples
86+
"gallery_dirs": ["examples"],
87+
# Pattern to search for example files
88+
"filename_pattern": r"\.py",
89+
# Remove the "Download all examples" button from the top level gallery
90+
"download_all_examples": False,
91+
# Sort gallery example by file name instead of number of lines (default)
92+
# directory where function granular galleries are stored
93+
"backreferences_dir": None,
94+
# Modules for which function level galleries are created. In
95+
"doc_module": "allie-flowkit-python",
96+
"ignore_pattern": "flycheck*",
97+
"thumbnail_size": (350, 350),
98+
"remove_config_comments": True,
99+
"show_signature": False,
100+
}
101+
102+
103+
# Intersphinx mapping
104+
intersphinx_mapping = {
105+
"python": ("https://docs.python.org/3.11", None),
106+
"numpy": ("https://numpy.org/doc/stable", None),
107+
"scipy": ("https://docs.scipy.org/doc/scipy/", None),
108+
"pyvista": ("https://docs.pyvista.org/version/stable", None),
109+
"grpc": ("https://grpc.github.io/grpc/python/", None),
110+
"pint": ("https://pint.readthedocs.io/en/stable", None),
111+
"beartype": ("https://beartype.readthedocs.io/en/stable/", None),
112+
"docker": ("https://docker-py.readthedocs.io/en/stable/", None),
113+
"pypim": ("https://pypim.docs.pyansys.com/version/stable", None),
114+
}
115+
116+
# numpydoc configuration
117+
numpydoc_show_class_members = False
118+
numpydoc_xref_param_type = True
119+
120+
# Consider enabling numpydoc validation. See:
121+
# https://numpydoc.readthedocs.io/en/latest/validation.html#
122+
numpydoc_validate = True
123+
numpydoc_validation_checks = {
124+
"GL06", # Found unknown section
125+
"GL07", # Sections are in the wrong order.
126+
# "GL08", # The object does not have a docstring
127+
"GL09", # Deprecation warning should precede extended summary
128+
"GL10", # reST directives {directives} must be followed by two colons
129+
"SS01", # No summary found
130+
"SS02", # Summary does not start with a capital letter
131+
# "SS03", # Summary does not end with a period
132+
"SS04", # Summary contains heading whitespaces
133+
# "SS05", # Summary must start with infinitive verb, not third person
134+
"RT02", # The first line of the Returns section should contain only the
135+
# type, unless multiple values are being returned"
136+
}
137+
138+
html_favicon = ansys_favicon
139+
140+
# Add any paths that contain templates here, relative to this directory.
141+
templates_path = ["_templates"]
142+
143+
# The suffix(es) of source filenames.
144+
source_suffix = {
145+
".rst": "restructuredtext",
146+
".md": "markdown",
147+
}
148+
149+
# The master toctree document.
150+
master_doc = "index"
151+
152+
# Configuration for Sphinx autoapi
153+
autoapi_type = "python"
154+
autoapi_dirs = ["../../src"]
155+
autoapi_root = "api"
156+
autoapi_template_dir = get_autoapi_templates_dir_relative_path(Path(__file__))
157+
suppress_warnings = ["autoapi.python_import_resolution", "design.grid", "config.cache", "autoapi.not_readable"]
158+
autoapi_python_use_implicit_namespaces = True
159+
autoapi_keep_files = True
160+
autoapi_own_page_level = "class"
161+
autoapi_add_toctree_entry = False
162+
# Examples gallery customization
163+
nbsphinx_execute = "always"
164+
165+
nbsphinx_epilog = """
166+
----
167+
168+
.. admonition:: Download this example
169+
170+
Download this example as a `Jupyter Notebook <{cname_pref}/{ipynb_file_loc}>`_
171+
or as a `Python script <{cname_pref}/{py_file_loc}>`_.
172+
173+
""".format(
174+
cname_pref=f"https://{cname}/version/{switcher_version}",
175+
ipynb_file_loc="{{ env.docname }}.ipynb",
176+
py_file_loc="{{ env.docname }}.py",
177+
)
178+
179+
nbsphinx_prolog = """
180+
181+
.. admonition:: Download this example
182+
183+
Download this example as a `Jupyter Notebook <{cname_pref}/{ipynb_file_loc}>`_
184+
or as a `Python script <{cname_pref}/{py_file_loc}>`_.
185+
186+
----
187+
""".format(
188+
cname_pref=f"https://{cname}/version/{switcher_version}",
189+
ipynb_file_loc="{{ env.docname }}.ipynb",
190+
py_file_loc="{{ env.docname }}.py",
191+
)
192+
193+
typehints_defaults = "comma"
194+
simplify_optional_unions = False
195+
196+
# additional logos for the latex coverpage
197+
latex_additional_files = [watermark, ansys_logo_white, ansys_logo_white_cropped]
198+
199+
# change the preamble of latex with customized title page
200+
# variables are the title of pdf, watermark
201+
latex_elements = {"preamble": latex.generate_preamble(html_title)}
202+
203+
linkcheck_exclude_documents = ["index", "getting_started/local/index", "assets"]
204+
205+
# -- Declare the Jinja context -----------------------------------------------
206+
exclude_patterns = [
207+
"examples/**/*.ipynb",
208+
"examples/**/*.py",
209+
"examples/**/*.md5",
210+
"api/ansys/visualizer/index.rst",
211+
]
212+
213+
BUILD_API = True
214+
if not BUILD_API:
215+
exclude_patterns.append("autoapi")
216+
217+
BUILD_EXAMPLES = True
218+
if not BUILD_EXAMPLES:
219+
exclude_patterns.append("examples/**")
220+
exclude_patterns.append("examples.rst")
221+
222+
jinja_contexts = {
223+
"main_toctree": {
224+
"build_api": BUILD_API,
225+
"build_examples": BUILD_EXAMPLES,
226+
}
227+
}
228+
229+
230+
def prepare_jinja_env(jinja_env) -> None:
231+
"""Customize the jinja env.
232+
233+
Notes
234+
-----
235+
See https://jinja.palletsprojects.com/en/3.0.x/api/#jinja2.Environment
236+
237+
"""
238+
jinja_env.globals["project_name"] = project
239+
240+
241+
autoapi_prepare_jinja_env = prepare_jinja_env

‎doc/source/contributing.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _contribute:
2+
3+
Contribute
4+
##########
5+
6+
Overall guidance on contributing to a PyAnsys library appears in the
7+
`Contributing <https://dev.docs.pyansys.com/how-to/contributing.html>`_ topic
8+
in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar
9+
with this guide before attempting to contribute to the Allie Flowkit Python.
10+
11+
The following contribution information is specific to the Allie Flowkit Python.

‎doc/source/examples/index.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _ref_examples:
2+
3+
Examples
4+
========
5+
6+
This section show how to use the Allie Flowkit Python to perform many different
7+
types of operations.

0 commit comments

Comments
 (0)