diff --git a/.github/workflows/ci_cd_pr.yml b/.github/workflows/ci_cd_pr.yml index 55992d5fb8..dd3059f4a8 100644 --- a/.github/workflows/ci_cd_pr.yml +++ b/.github/workflows/ci_cd_pr.yml @@ -136,107 +136,146 @@ jobs: with: token: ${{ secrets.GITHUB_TOKEN }} - doc: - name: "Documentation build" + # doc: + # name: "Documentation build" + # runs-on: ubuntu-latest + # needs: [doc-style] + # steps: + # - name: "Checkout project" + # uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + # with: + # persist-credentials: true + + # - name: "Build documentation" + # uses: ./.github/actions/doc-build + # with: + # timeout-mins: 7200 + # PyDynaRunContainer: ${{ env.PYDYNA_RUN_CONTAINER }} + # python-version: ${{ env.MAIN_PYTHON_VERSION }} + # github-token: ${{ secrets.GITHUB_TOKEN }} + # license-server: ${{ secrets.LICENSE_SERVER }} + # bot-token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }} + # github-actor: ${{ github.actor }} + + doc-build-keywords: + name: Doc building For keyword documentation runs-on: ubuntu-latest - needs: [doc-style] + needs: doc-style steps: - - name: "Checkout project" - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + - name: Checkout project + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 with: persist-credentials: true - - name: "Build documentation" - uses: ./.github/actions/doc-build + - name: Set up Python + uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 with: - timeout-mins: 7200 - PyDynaRunContainer: ${{ env.PYDYNA_RUN_CONTAINER }} python-version: ${{ env.MAIN_PYTHON_VERSION }} - github-token: ${{ secrets.GITHUB_TOKEN }} - license-server: ${{ secrets.LICENSE_SERVER }} - bot-token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }} - github-actor: ${{ github.actor }} - - smoke-tests: - name: "Build wheelhouse for ${{ matrix.os }} and Python ${{ matrix.python-version }}" - runs-on: ${{ matrix.os }} - needs: [code-style] - strategy: - fail-fast: false - matrix: - os: [windows-latest, ubuntu-latest] - python-version: ['3.10', '3.11', '3.12', '3.13'] - steps: - - uses: ansys/actions/build-wheelhouse@c2fa7c93f6883114e0e643599431b33d29f0b13f # v9.0.15 + + # - name: Install system dependencies + # run: | + # sudo apt-get update + # sudo apt-get install xvfb pandoc texlive-latex-extra latexmk + # shell: bash + + - name: Install python dependencies + run: | + python -m pip install .[doc] + shell: bash + + - name: Build keyword documentation + run: | + make -C doc html + shell: bash + env: + BUILD_EXAMPLES: 'false' + + - name: Upload keyword documentation artifact + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 with: - library-name: ${{ env.PACKAGE_NAME }} - operating-system: ${{ matrix.os }} - python-version: ${{ matrix.python-version }} + name: keyword-documentation + path: doc/_build/html/ + + # smoke-tests: + # name: "Build wheelhouse for ${{ matrix.os }} and Python ${{ matrix.python-version }}" + # runs-on: ${{ matrix.os }} + # needs: [code-style] + # strategy: + # fail-fast: false + # matrix: + # os: [windows-latest, ubuntu-latest] + # python-version: ['3.10', '3.11', '3.12', '3.13'] + # steps: + # - uses: ansys/actions/build-wheelhouse@c2fa7c93f6883114e0e643599431b33d29f0b13f # v9.0.15 + # with: + # library-name: ${{ env.PACKAGE_NAME }} + # operating-system: ${{ matrix.os }} + # python-version: ${{ matrix.python-version }} - keyword-testing: - name: "Keyword testing for matrix" - needs: [smoke-tests] - runs-on: ${{ matrix.os }} - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, windows-latest] - python-version: ['3.10', '3.11', '3.12', '3.13'] - steps: - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - persist-credentials: false + # keyword-testing: + # name: "Keyword testing for matrix" + # needs: [smoke-tests] + # runs-on: ${{ matrix.os }} + # strategy: + # fail-fast: false + # matrix: + # os: [ubuntu-latest, windows-latest] + # python-version: ['3.10', '3.11', '3.12', '3.13'] + # steps: + # - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + # with: + # persist-credentials: false - - name: Run test with "keywords" marker - uses: ./.github/actions/unit-test - with: - python-version: ${{ matrix.python-version }} - github-token: ${{ secrets.GITHUB_TOKEN }} - pytest-markers: keywords - coverage-file: keywords + # - name: Run test with "keywords" marker + # uses: ./.github/actions/unit-test + # with: + # python-version: ${{ matrix.python-version }} + # github-token: ${{ secrets.GITHUB_TOKEN }} + # pytest-markers: keywords + # coverage-file: keywords - run-testing: - name: Test the "run" subpackage - runs-on: ubuntu-latest - # needs: [smoke-tests] - steps: - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - persist-credentials: false + # run-testing: + # name: Test the "run" subpackage + # runs-on: ubuntu-latest + # # needs: [smoke-tests] + # steps: + # - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + # with: + # persist-credentials: false - - uses: ./.github/actions/unit-test - with: - python-version: ${{ env.MAIN_PYTHON_VERSION }} - github-token: ${{ secrets.GITHUB_TOKEN }} - docker-image: ${{ env.PYDYNA_RUN_CONTAINER }} - pytest-markers: run - license-server: ${{ secrets.LICENSE_SERVER }} - coverage-file: run - - unit-tests: - name: "Testing" - runs-on: ubuntu-latest - needs: [keyword-testing, run-testing, codegen-testing] - steps: - - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - with: - persist-credentials: false - - name: Run test without marker - uses: ./.github/actions/unit-test - with: - python-version: ${{ env.MAIN_PYTHON_VERSION }} - github-token: ${{ secrets.GITHUB_TOKEN }} - server-logs: true - codecov-token: ${{ env.CODECOV_TOKEN }} - coverage-file: unittests - - build-library: - name: "Build library" - needs: [doc, unit-tests] - runs-on: ubuntu-latest - steps: - - uses: ansys/actions/build-library@c2fa7c93f6883114e0e643599431b33d29f0b13f # v9.0.15 - with: - library-name: ${{ env.PACKAGE_NAME }} - python-version: ${{ env.MAIN_PYTHON_VERSION }} \ No newline at end of file + # - uses: ./.github/actions/unit-test + # with: + # python-version: ${{ env.MAIN_PYTHON_VERSION }} + # github-token: ${{ secrets.GITHUB_TOKEN }} + # docker-image: ${{ env.PYDYNA_RUN_CONTAINER }} + # pytest-markers: run + # license-server: ${{ secrets.LICENSE_SERVER }} + # coverage-file: run + + # unit-tests: + # name: "Testing" + # runs-on: ubuntu-latest + # needs: [keyword-testing, run-testing, codegen-testing] + # steps: + # - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 + # with: + # persist-credentials: false + # - name: Run test without marker + # uses: ./.github/actions/unit-test + # with: + # python-version: ${{ env.MAIN_PYTHON_VERSION }} + # github-token: ${{ secrets.GITHUB_TOKEN }} + # server-logs: true + # codecov-token: ${{ env.CODECOV_TOKEN }} + # coverage-file: unittests + + # build-library: + # name: "Build library" + # needs: [doc, unit-tests] + # runs-on: ubuntu-latest + # steps: + # - uses: ansys/actions/build-library@c2fa7c93f6883114e0e643599431b33d29f0b13f # v9.0.15 + # with: + # library-name: ${{ env.PACKAGE_NAME }} + # python-version: ${{ env.MAIN_PYTHON_VERSION }} \ No newline at end of file diff --git a/.gitignore b/.gitignore index 39cc491225..71c440d781 100644 --- a/.gitignore +++ b/.gitignore @@ -165,3 +165,5 @@ cython_debug/ doc/source/examples/ doc/source/API/_autosummary/ doc/source/api +_build/ +doc/source/keyword_classes_doc/api/ \ No newline at end of file diff --git a/doc/changelog/930.added.md b/doc/changelog/930.added.md new file mode 100644 index 0000000000..5ad2c7d355 --- /dev/null +++ b/doc/changelog/930.added.md @@ -0,0 +1 @@ +Test api rst files diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000000..bc74a75cae --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,26 @@ +API reference +============= + +This section describes PyDYNA's endpoints, their capabilities, and how +to interact with them programmatically. + + + + +.. jinja:: main_toctree + + .. toctree:: + :hidden: + :maxdepth: 3 + + {% if build_api %} + {% for page in pages %} + {% set length = autoapi_depth | int %} + {% if (page.top_level_object or page.name.split('.') | length == length) and page.display %} + {{ page.name }}<{{ page.include_path }}> + {% endif %} + {% endfor %} + Auto Keyword classes<../_autosummary/index> + {% endif %} + + diff --git a/doc/source/conf.py b/doc/source/conf.py index d10f9f1daa..acab8d9618 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -90,7 +90,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "sphinx_boogergreen_theme_1", "Thumbs.db", ".DS_Store", "*.txt", "links.rst", "keyword_classes/**"] +exclude_patterns = ["_build", "sphinx_boogergreen_theme_1", "Thumbs.db", ".DS_Store", "*.txt", "links.rst", "keyword_classes/**", "keyword_classes_doc/**"] # make rst_epilog a variable, so you can add other epilog parts to it rst_epilog = "" @@ -131,9 +131,9 @@ "collapse_navigation": True, "use_edit_page_button": True, "ansys_sphinx_theme_autoapi": { - "ignore": [ - "*core/keywords/keyword_classes/auto*", - ], + # "ignore": [ + # "*core/keywords/keyword_classes/auto*", + # ], "output": "api", }, } diff --git a/doc/source/example.rst b/doc/source/example.rst new file mode 100644 index 0000000000..4519841e6b --- /dev/null +++ b/doc/source/example.rst @@ -0,0 +1,16 @@ +Examples +======== + +This section provides examples of how to use PyDYNA in various scenarios. + + + +.. jinja:: main_toctree + + .. toctree:: + :hidden: + :maxdepth: 3 + + {% if build_examples %} + examples/index + {% endif %} \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index 166557166c..2deeaf81be 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -66,11 +66,7 @@ PyDYNA documentation |version| getting-started user-guide/index - {% if build_api %} - api/index - {% endif %} - {% if build_examples %} - examples/index - {% endif %} + api.rst + examples.rst contributing changelog diff --git a/doc/source/keyword_classes_doc/Makefile b/doc/source/keyword_classes_doc/Makefile new file mode 100644 index 0000000000..02d493a3e9 --- /dev/null +++ b/doc/source/keyword_classes_doc/Makefile @@ -0,0 +1,30 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS = -j auto +SPHINXBUILD = sphinx-build +SOURCEDIR = +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile clean pdf keyword_classes + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +do +clean: + rm -rf $(BUILDDIR)/* + rm -rf source/examples/gallery_examples + find . -type d -name $(APIDIR) -exec rm -rf {} + + +pdf: + @$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true + (test -f $(BUILDDIR)/latex/*.pdf && echo pdf exists) || exit 1 diff --git a/doc/source/keyword_classes_doc/conf.py b/doc/source/keyword_classes_doc/conf.py new file mode 100755 index 0000000000..e369e39648 --- /dev/null +++ b/doc/source/keyword_classes_doc/conf.py @@ -0,0 +1,204 @@ +#import ansys.dyna.solver as solver + +import datetime +import os + +from ansys_sphinx_theme import get_version_match, ansys_favicon + +from ansys.dyna.core import __version__ + +# Project information +project = 'ansys-dyna-core' +copyright = f"(c) {datetime.datetime.now().year} ANSYS, Inc. All rights reserved" +author = 'ANSYS Inc.' +release = version = __version__ +cname = os.getenv("DOCUMENTATION_CNAME", default="dyna.docs.pyansys.com") + +# Sphinx extensions +extensions = [ + 'sphinx.ext.intersphinx', + 'numpydoc', + # "sphinx_jinja", + "sphinx_design", + "ansys_sphinx_theme.extension.autoapi", +] + +# Intersphinx mapping +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "numpy": ("https://numpy.org/devdocs", None), + "matplotlib": ("https://matplotlib.org/stable", None), + "imageio": ("https://imageio.readthedocs.io/en/stable", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None), + "pytest": ("https://docs.pytest.org/en/stable", None), + } + +# Numpydoc config +numpydoc_use_plots = True +numpydoc_show_class_members = False # we take care of autosummary on our own +numpydoc_xref_param_type = True +numpydoc_validate = True +numpydoc_validation_checks = { + # general + "GL06", # Found unknown section + "GL07", # Sections are in the wrong order. + # "GL08", # The object does not have a docstring + "GL09", # Deprecation warning should precede extended summary + "GL10", # reST directives {directives} must be followed by two colons + # Summary + # "SS01", # No summary found + # "SS02", # Summary does not start with a capital letter + #"SS03", # Summary does not end with a period + "SS04", # Summary contains heading whitespaces + "SS05", # Summary must start with infinitive verb, not third person + # Parameters + #"PR10", # Parameter "{param_name}" requires a space before the colon ' + # separating the parameter name and type", +} + + +# Favicon +html_favicon = ansys_favicon + +# The suffix(es) of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# The language for content autogenerated by Sphinx_PyAEDT. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +# exclude_patterns = ["_build", "sphinx_boogergreen_theme_1", "Thumbs.db", ".DS_Store", "*.txt", "links.rst", "keyword_classes/**"] + +# make rst_epilog a variable, so you can add other epilog parts to it +# rst_epilog = "" + +# # Read link all targets from file +# with open("links.rst") as f: +# rst_epilog += f.read() + +inheritance_graph_attrs = dict(rankdir="RL", size='"8.0, 10.0"', fontsize=14, ratio="compress") +inheritance_node_attrs = dict(shape="ellipse", fontsize=14, height=0.75, color="dodgerblue1", style="filled") + +# -- Options for HTML output ------------------------------------------------- +html_short_title = html_title = "PyDYNA keywords" +html_show_sourcelink = True +html_theme = "ansys_sphinx_theme" +html_context = { + "github_user": "ansys", + "github_repo": "pydyna", + "github_version": "main", + "doc_path": "doc/source", + "pyansys_tags": [ + "Structures" + ] +} +html_theme_options = { + "logo": "pyansys", + "switcher": { + "json_url": f"https://{cname}/versions.json", + "version_match": get_version_match(__version__), + }, + "github_url": "https://github.com/ansys/pydyna", + "show_prev_next": False, + "show_breadcrumbs": True, + "additional_breadcrumbs": [ + ("PyAnsys", "https://docs.pyansys.com/"), + ], + "collapse_navigation": True, + "use_edit_page_button": True, + "ansys_sphinx_theme_autoapi": { + "output": "api", + "directory": "../../../src/ansys/dyna/core/keywords/keyword_classes/auto", + }, +} + +# static path +html_static_path = ['_static'] + + +# # -- Declare the Jinja context ----------------------------------------------- +# BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False +# if not BUILD_API: +# exclude_patterns.append("api") +# html_theme_options.pop("ansys_sphinx_theme_autoapi") +# extensions.remove("ansys_sphinx_theme.extension.autoapi") + +# suppress_warnings = ["autoapi.python_import_resolution", "config.cache", "docutils"] + +# BUILD_AUTOKEYWORS_API = os.environ.get("BUILD_AUTOKEYWORS_API", "false").lower() == "true" +# if BUILD_AUTOKEYWORS_API: +# html_theme_options["ansys_sphinx_theme_autoapi"]["templates"] = "autoapi/" + +# BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False +# if BUILD_EXAMPLES is True: +# # Necessary for pyvista when building the sphinx gallery +# extensions.append("sphinx_gallery.gen_gallery") +# pyvista.BUILDING_GALLERY = True +# sphinx_gallery_conf = { +# # convert rst to md for ipynb +# "pypandoc": True, +# # path to your examples scripts +# "examples_dirs": ["../../examples/"], +# # path where to save gallery generated examples +# "gallery_dirs": ["examples"], +# # Patter to search for examples files +# "filename_pattern": r"\.py", +# # Patter to omit some files +# "ignore_pattern": r"/*_data.py", +# # Remove the "Download all examples" button from the top level gallery +# "download_all_examples": False, +# # Sort gallery examples by file name instead of number of lines (default) +# "within_subsection_order": FileNameSortKey, +# # directory where function granular galleries are stored +# "backreferences_dir": None, +# # Modules for which function level galleries are created. In +# "doc_module": "ansys-dyna-core", +# "image_scrapers": ("pyvista", "matplotlib"), +# "thumbnail_size": (600, 300), +# # 'first_notebook_cell': ("%matplotlib inline\n" +# # "from pyvista import set_plot_theme\n" +# # "set_plot_theme('document')"), +# 'remove_config_comments': True, +# } + +# jinja_contexts = { +# "main_toctree": { +# "build_api": BUILD_API, +# "build_examples": BUILD_EXAMPLES, +# }, +# } + +# def skip_run_subpackage(app, what, name, obj, skip, options): +# """Skip specific members of the 'run' subpackage during documentation generation. + +# This function skips: +# - All modules under 'ansys.dyna.core.run' except 'local_solver' and 'options'. +# - Within 'local_solver', skips all members except the 'run_dyna' function. +# """ + + +# if name.startswith("ansys.dyna.core.run.") and not (name.startswith("ansys.dyna.core.run.local_solver") or name.startswith("ansys.dyna.core.run.options")): +# skip = True + +# if name.startswith("ansys.dyna.core.run.local_solver"): +# if what == "function" and name!= "ansys.dyna.core.run.local_solver.run_dyna": +# skip = True + +# return skip + + +# def setup(sphinx): +# """Add custom extensions to Sphinx.""" +# sphinx.connect("autoapi-skip-member", skip_run_subpackage) \ No newline at end of file diff --git a/doc/source/keyword_classes_doc/index.rst b/doc/source/keyword_classes_doc/index.rst new file mode 100644 index 0000000000..8a4494aa45 --- /dev/null +++ b/doc/source/keyword_classes_doc/index.rst @@ -0,0 +1,26 @@ +The ``keyword_classes`` auto-generated keyword classes +======================================================= +This section contains the auto-generated documentation for all the keyword classes in the `pydyna` package. +Each class corresponds to a specific keyword used in LS-DYNA input files, providing a structured way to interact with these keywords programmatically. + +.. toctree:: + :titlesonly: + :maxdepth: 3 + + auto_keywords + + + + + + + + + + + + + + + +