|
2 | 2 |
|
3 | 3 | from datetime import datetime |
4 | 4 | import os |
| 5 | +import pathlib |
| 6 | +import shutil |
5 | 7 |
|
6 | 8 | from ansys_sphinx_theme import get_version_match |
7 | 9 | from ansys_sphinx_theme import pyansys_logo_black as logo |
| 10 | +import sphinx |
| 11 | +from sphinx.util import logging |
8 | 12 |
|
9 | 13 | from ansys.conceptev.core import __version__ |
10 | 14 |
|
| 15 | +logger = logging.getLogger(__name__) |
| 16 | +path = pathlib.Path(__file__).parent.parent.parent / "examples" |
| 17 | +EXAMPLES_DIRECTORY = path.resolve() |
| 18 | + |
11 | 19 | # Project information |
12 | 20 | project = "ansys-conceptev-core" |
13 | 21 | copyright = f"(c) 2023-{datetime.today().year} ANSYS, Inc. and/or its affiliates." |
14 | 22 | author = "ANSYS, Inc." |
15 | 23 | release = version = __version__ |
16 | | -cname = os.getenv("DOCUMENTATION_CNAME", "docs.pyansys.com") |
| 24 | +cname = os.getenv("DOCUMENTATION_CNAME", "conceptev.core.docs.pyansys.com") |
17 | 25 | switcher_version = get_version_match(__version__) |
18 | 26 |
|
19 | 27 | # Select desired logo, theme, and declare the html title |
|
29 | 37 |
|
30 | 38 | # specify the location of your github repo |
31 | 39 | html_theme_options = { |
32 | | - "github_url": "https://github.com/pyconceptev-core", |
| 40 | + "github_url": "https://github.com/ansys/pyconceptev-core", |
33 | 41 | "use_edit_page_button": True, |
34 | 42 | "show_prev_next": False, |
35 | 43 | "show_breadcrumbs": True, |
|
45 | 53 |
|
46 | 54 | # Sphinx extensions |
47 | 55 | extensions = [ |
| 56 | + "nbsphinx", |
48 | 57 | "numpydoc", |
| 58 | + "recommonmark", |
49 | 59 | "sphinx.ext.autodoc", |
50 | 60 | "sphinx.ext.autosummary", |
51 | 61 | "sphinx.ext.imgconverter", |
|
81 | 91 | # type, unless multiple values are being returned" |
82 | 92 | } |
83 | 93 |
|
84 | | -# static path |
| 94 | +# Static path |
85 | 95 | html_static_path = ["_static"] |
| 96 | +html_css_files = [ |
| 97 | + "custom.css", |
| 98 | +] |
| 99 | + |
| 100 | +# List of patterns, relative to source directory, that match files and |
| 101 | +# directories to ignore when looking for source files. |
| 102 | +# This pattern also affects html_static_path and html_extra_path. |
| 103 | +exclude_patterns = [ |
| 104 | + "_build", |
| 105 | + "*.txt", |
| 106 | + "conf.py", |
| 107 | +] |
86 | 108 |
|
87 | 109 | # Add any paths that contain templates here, relative to this directory. |
88 | 110 | templates_path = ["_templates"] |
89 | 111 |
|
90 | 112 | # The suffix(es) of source filenames. |
91 | | -source_suffix = ".rst" |
| 113 | +source_suffix = { |
| 114 | + ".rst": "restructuredtext", |
| 115 | + ".md": "markdown", |
| 116 | +} |
92 | 117 |
|
93 | 118 | # The master toctree document. |
94 | 119 | master_doc = "index" |
95 | 120 |
|
96 | | -linkcheck_ignore = [] |
| 121 | +# Examples gallery customization |
| 122 | +nbsphinx_execute = "always" |
| 123 | +nbsphinx_allow_errors = False |
| 124 | +nbsphinx_thumbnails = { |
| 125 | + "examples/simple_workflow": "_static/thumbnails/simple_workflow.png", |
| 126 | +} |
| 127 | +nbsphinx_custom_formats = { |
| 128 | + ".py": ["jupytext.reads", {"fmt": ""}], |
| 129 | +} |
| 130 | + |
| 131 | +# Activate fontawesome icons in LaTeX |
| 132 | +sd_fontawesome_latex = True |
| 133 | + |
| 134 | +linkcheck_exclude_documents = ["index"] |
| 135 | +linkcheck_ignore = [ |
| 136 | + r"https://download.ansys.com/", |
| 137 | + r".*/examples/.*.py", |
| 138 | + r"_static/assets/.*", |
| 139 | +] |
| 140 | + |
97 | 141 |
|
98 | 142 | # If we are on a release, we have to ignore the "release" URLs, since it is not |
99 | 143 | # available until the release is published. |
100 | 144 | if switcher_version != "dev": |
101 | 145 | linkcheck_ignore.append( |
102 | 146 | f"https://github.com/ansys/pyconceptev-core/releases/tag/v{__version__}" |
103 | 147 | ) |
| 148 | + |
| 149 | +# Sphinx event hooks |
| 150 | + |
| 151 | + |
| 152 | +def directory_size(directory_path): |
| 153 | + """Compute the size (in mega bytes) of a directory.""" |
| 154 | + res = 0 |
| 155 | + for path, _, files in os.walk(directory_path): |
| 156 | + for f in files: |
| 157 | + fp = os.path.join(path, f) |
| 158 | + res += os.stat(fp).st_size |
| 159 | + # Convert in mega bytes |
| 160 | + res /= 1e6 |
| 161 | + return res |
| 162 | + |
| 163 | + |
| 164 | +def check_pandoc_installed(app): |
| 165 | + """Ensure that pandoc is installed.""" |
| 166 | + import pypandoc |
| 167 | + |
| 168 | + try: |
| 169 | + pandoc_path = pypandoc.get_pandoc_path() |
| 170 | + pandoc_dir = os.path.dirname(pandoc_path) |
| 171 | + if pandoc_dir not in os.environ["PATH"].split(os.pathsep): |
| 172 | + logger.info("Pandoc directory is not in $PATH.") |
| 173 | + os.environ["PATH"] += os.pathsep + pandoc_dir |
| 174 | + logger.info(f"Pandoc directory '{pandoc_dir}' has been added to $PATH") |
| 175 | + except OSError: |
| 176 | + logger.error("Pandoc was not found, please add it to your path or install pypandoc-binary") |
| 177 | + |
| 178 | + |
| 179 | +def copy_examples(app): |
| 180 | + """Copy directory examples (root directory) files into the doc/source/examples directory.""" |
| 181 | + destination_dir = pathlib.Path(app.srcdir, "examples").resolve() |
| 182 | + logger.info(f"Copying examples from {EXAMPLES_DIRECTORY} to {destination_dir}.") |
| 183 | + |
| 184 | + if os.path.exists(destination_dir): |
| 185 | + size = directory_size(destination_dir) |
| 186 | + logger.info(f"Directory {destination_dir} ({size} MB) already exist, removing it.") |
| 187 | + shutil.rmtree(destination_dir) |
| 188 | + logger.info(f"Directory removed.") |
| 189 | + |
| 190 | + shutil.copytree(EXAMPLES_DIRECTORY, destination_dir) |
| 191 | + logger.info(f"Copy performed") |
| 192 | + |
| 193 | + |
| 194 | +def remove_examples(app, exception): |
| 195 | + """Remove the doc/source/examples directory created during the documentation build.""" |
| 196 | + destination_dir = pathlib.Path(app.srcdir) / "examples" |
| 197 | + |
| 198 | + size = directory_size(destination_dir) |
| 199 | + logger.info(f"Removing directory {destination_dir} ({size} MB).") |
| 200 | + shutil.rmtree(destination_dir, ignore_errors=True) |
| 201 | + logger.info(f"Directory removed.") |
| 202 | + |
| 203 | + |
| 204 | +def setup(app: sphinx.application.Sphinx): |
| 205 | + """Run different hook functions during the documentation build. |
| 206 | +
|
| 207 | + Parameters |
| 208 | + ---------- |
| 209 | + app : sphinx.application.Sphinx |
| 210 | + Sphinx instance containing all the configuration for the documentation build. |
| 211 | + """ |
| 212 | + app.connect("builder-inited", copy_examples) |
| 213 | + app.connect("builder-inited", check_pandoc_installed) |
| 214 | + app.connect("build-finished", remove_examples) |
0 commit comments