Jeff/doc template for troubleshooting

.github/workflows/ci_cd.yml

@@ -113,7 +113,7 @@ jobs:
   docs:
     name: Documentation
     needs: [ docs-style ]
-    runs-on: ubuntu-latest
+    runs-on: [ self-hosted, pysherlock ]
     steps:
       - name: Run documentation building action
         uses: ansys/actions/doc-build@v8

.gitignore

@@ -53,3 +53,6 @@ test-output.xml
 .idea/
 PySherlock.log.*
 doc/build/
+
+doc/source/examples/gallery_examples/*
+doc/source/sg_execution_times.rst

doc/Makefile

@@ -21,11 +21,20 @@ help:
 
 # Customized clean due to examples gallery
 clean:
+	@echo "Cleaning everything."
 	rm -rf $(BUILDDIR)/*
+	rm -rf images/auto-generated
+	rm -rf source/examples/gallery_examples
 	find . -type d -name "_autosummary" -exec rm -rf {} +
 
+# clean only examples
+clean-examples:
+	@echo "Cleaning only the examples."
+	rm -rf source/examples/gallery_examples
+
 # Create PDF
 pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	cd $(BUILDDIR)/latex && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
 	(test -f $(BUILDDIR)/latex/ansys-sherlock-core.pdf && echo pdf exists) || exit 1
+

doc/changelog.d/480.documentation.md

@@ -0,0 +1 @@
+DOC: New documentation of PySherlock

doc/changelog.d/486.documentation.md

@@ -0,0 +1 @@
+Jeff/doc template for troubleshooting

doc/make.bat

@@ -1,4 +1,4 @@
-@ECHO OFF
+@ECHO ON
 
 pushd %~dp0
 
@@ -12,8 +12,10 @@ set BUILDDIR=_build
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
+if "%1" == "clean-examples" goto clean-examples
 if "%1" == "pdf" goto pdf
 if "%1" == "html" goto html
+if "%1" == "html-examples" goto html-examples
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -31,13 +33,23 @@ if errorlevel 9009 (
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
-:html
+:html-examples
 %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
+:html
+%SPHINXBUILD% -D plot_gallery=0 -b html %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS% %O%
+goto end
+
 :clean
 rmdir /s /q %BUILDDIR% > /NUL 2>&1
 for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
+rmdir /s /q source\examples\gallery_examples > /NUL 2>&1
+goto end
+
+:clean-examples
+echo Cleaning examples
+rmdir /s /q source\examples\gallery_examples > /NUL 2>&1
 goto end
 
 :help

doc/source/404.rst

@@ -0,0 +1,8 @@
+:orphan:
+
+Oops
+====
+
+This is unexpected.
+
+The page you are requesting does not exist.

doc/source/conf.py

@@ -2,6 +2,7 @@
 
 from datetime import datetime
 import os
+from pathlib import Path
 
 from ansys_sphinx_theme import (
     ansys_favicon,
@@ -13,7 +14,10 @@
     watermark,
 )
 from sphinx.builders.latex import LaTeXBuilder
+from sphinx.util import logging
+from sphinx_gallery.sorting import FileNameSortKey
 
+from ansys.sherlock import core as pysherlock
 from ansys.sherlock.core import __version__
 
 LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
@@ -23,7 +27,7 @@
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "ANSYS Inc."
 release = version = __version__
-cname = os.getenv("DOCUMENTATION_CNAME", default="nocname.com")
+cname = os.getenv("DOCUMENTATION_CNAME", default="sherlock.docs.pyansys.com")
 switcher_version = get_version_match(__version__)
 
 # Select desired logo, theme, and declare the html title
@@ -32,14 +36,29 @@
 html_short_title = html_title = "PySherlock"
 html_favicon = ansys_favicon
 
+# Convert notebooks into Python scripts and include them in the output files
+logger = logging.getLogger(__name__)
+
+pysherlock.BUILDING_GALLERY = True
+
+DEFAULT_EXAMPLE_EXTENSION = "py"
+DOC_PATH = "doc/source"
+GALLERY_EXAMPLES_PATH = "examples/gallery_examples"
+EXAMPLES_ROOT = "examples"
+EXAMPLES_PATH_FOR_DOCS = f"../../{EXAMPLES_ROOT}/"
+
+SOURCE_PATH = Path(__file__).parent.resolve().absolute()
+pyansys_light_mode_logo = str(os.path.join(SOURCE_PATH, "_static", "pyansys-logo-light_mode.png"))
+
 # specify the location of your github repo
 html_context = {
     "github_user": "ansys",
     "github_repo": "pysherlock",
     "github_version": "main",
-    "doc_path": "doc/source",
+    "doc_path": str(DOC_PATH),
 }
 html_theme_options = {
+    "logo": "pyansys",
     "switcher": {
         "json_url": f"https://{cname}/versions.json",
         "version_match": switcher_version,
@@ -50,6 +69,7 @@
     "show_breadcrumbs": True,
     "collapse_navigation": True,
     "use_edit_page_button": True,
+    "header_links_before_dropdown": 5,  # number of links before the dropdown menu
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],
@@ -64,13 +84,29 @@
 
 # Sphinx extensions
 extensions = [
+    "jupyter_sphinx",
+    "notfound.extension",
+    "numpydoc",
     "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
     "sphinx_design",
+    "sphinx_gallery.gen_gallery",
+    "sphinxemoji.sphinxemoji",
+    "ansys_sphinx_theme.extension.linkcode",
 ]
 
+# notfound.extension
+notfound_template = "404.rst"
+notfound_urls_prefix = "/../"
+
 autodoc_default_flags = ["members"]
 autosummary_generate = True
 
@@ -85,6 +121,9 @@
 
 # static path
 html_static_path = ["_static"]
+templates_path = ["_templates"]
+# The suffix(es) of source filenames.
+source_suffix = ".rst"
 
 # We have our own custom templates
 templates_path = ["_templates"]
@@ -123,5 +162,75 @@
 if switcher_version != "dev":
     linkcheck_ignore.append(f"https://github.com/ansys/pysherlock/releases/tag/v{version}")
 
-# Suprpress warnings
-suppress_warnings = ["design.grid", "design.fa-build"]
+
+# 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",
+    "links.rst",
+    # because we include this in examples/index.rst
+    f"{GALLERY_EXAMPLES_PATH}/index.rst",
+]
+
+# -- Sphinx Gallery Options ---------------------------------------------------
+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/gallery_examples"],
+    # Pattern to search for example files
+    "filename_pattern": r"\." + DEFAULT_EXAMPLE_EXTENSION,
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example 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-sherlock-core",
+    "ignore_pattern": "flycheck*",
+    "thumbnail_size": (350, 350),
+    "remove_config_comments": True,
+    "default_thumb_file": pyansys_light_mode_logo,
+    "show_signature": False,
+}
+
+# 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()
+rst_epilog = rst_epilog.replace("%%VERSION%%", f"v{release}")
+
+# Copy button customization ---------------------------------------------------
+# exclude traditional Python prompts from the copied code
+copybutton_prompt_text = r">>> ?|\.\.\. "
+copybutton_prompt_is_regexp = True
+
+# numpydoc configuration
+numpydoc_use_plots = True
+numpydoc_show_class_members = False
+numpydoc_xref_param_type = True
+numpydoc_validate = False
+numpydoc_validation_checks = {
+    # "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
+    "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
+    "RT02",  # The first line of the Returns section should contain only the
+    # type, unless multiple values are being returned"
+}
+
+suppress_warnings = ["label.*", "design.fa-build", "config.cache", "numpydoc.*"]
+
+# Display todos by setting to True
+todo_include_todos = True

doc/source/examples/index.rst

@@ -0,0 +1,55 @@
+.. toctree::
+    :hidden:
+    :maxdepth: 3
+
+    gallery_examples/00-importing-project-files/index.rst
+    gallery_examples/01-project-configuration/index.rst
+    gallery_examples/02-analyses/index.rst
+
+.. _ref_examples:
+
+Examples
+========
+
+Here are examples using Sherlock with the ``ansys-sherlock-core`` library.
+
+.. grid:: 2 2 3 3
+   :gutter: 1 2 3 3
+   :padding: 1 2 3 3
+
+
+   .. grid-item-card:: Importing Projects and Files
+      :link: sphx_glr_examples_gallery_examples_00-importing-project-files
+      :link-type: ref
+
+      Examples on how to import projects and files using PySherlock.
+
+   .. grid-item-card:: Project Configuration
+      :link: sphx_glr_examples_gallery_examples_01-project-configuration
+      :link-type: ref
+
+      Examples on how to configure a project using PySherlock.
+
+   .. grid-item-card:: Running Analyses
+      :link: sphx_glr_examples_gallery_examples_02-analyses
+      :link-type: ref
+
+      Examples on how to run analyses using PySherlock.
+
+
+.. === DOWNLOAD EXAMPLES ===
+
+.. _ref_download_files:
+
+Download example files
+======================
+
+Each example should contain all the necessary resources to run the example.
+However in some cases, external files are needed. A link to those files is
+available at each example page.
+These links refers to the following GitHub repository where you can find all of them:
+
+`GitHub Example Data Repository <example_data_repo_>`_
+
+If you find a missing or broken link, open an issue in
+GitHub (`PySherlock Issues <pysherlock_issues_>`_).