Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Feat/improve doc build logic #502

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Feat/improve doc build logic #502

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c89b7ca
feat: combined pre-build scripts into a single sphinx build-time hook
moe-ad Nov 28, 2024
7f917d9
feat: updated tox.ini to call sphinx-build directly
moe-ad Nov 28, 2024
12da443
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Nov 28, 2024
d7e7d6a
feat: implemented review comments and updated affected actions
moe-ad Nov 28, 2024
fef5eb5
feat: implemented review comments
moe-ad Dec 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 0 additions & 92 deletions archive_examples.py
View file
Open in desktop

This file was deleted.

88 changes: 74 additions & 14 deletions doc/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# Sphinx documentation configuration file
from datetime import datetime
import os
import pathlib
from pathlib import Path
import shutil
import sys
from zipfile import ZipFile

from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
import sphinx
Expand Down Expand Up @@ -332,27 +333,86 @@ def prepare_jinja_env(jinja_env) -> None:
}


def copy_download_files_to_source_dir(app: sphinx.application.Sphinx) -> None:
def archive_examples(app: sphinx.application.Sphinx) -> None:
"""
Copy zipped example files to target directory at build time
Create a zip archive for each listed example included in the examples folder.

Parameters
----------
app : sphinx.application.Sphinx
Sphinx application instance containing the all the doc build configuration.

"""

# archive_examples.py in the root directory is being run before doc build (via tox)
# we simply need to copy the into the _download target defined in the .rst source files.
SOURCE_DIR = pathlib.Path(app.srcdir)
ZIPPED_FILES_DIR = SOURCE_DIR.parent.parent / "build"
DOWNLOAD_FILES_DIR = SOURCE_DIR.parent / "_build" / "html" / "_downloads"
DOWNLOAD_FILES_DIR.mkdir(exist_ok=True)

for file_path in ZIPPED_FILES_DIR.glob("*"):
EXAMPLES = {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why using all caps for variables like examples, source_dir etc?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is because those more or less do not change, like constants.
If you prefer, I can move examples to the top of the file and pass it as an argument to the function instead.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SOURCE_DIR should just be a lower case variable, it depends on the input app, it's not a constant.
Regarding EXAMPLES, either you move it outside of the function as a constant or you make it lower case inside the function. Either is fine with me.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Implemented your suggestions.

"mapdl_motorbike_frame": [
"project_setup.py",
"project_query.py",
"exec_mapdl.py",
"motorbike_frame_results.txt",
"motorbike_frame.mac",
],
"mapdl_tyre_performance": [
"project_setup.py",
"tire_performance_simulation.mac",
"2d_tire_geometry.iges",
],
"mapdl_linked_analyses": [
"project_setup.py",
"prestress.dat",
"modal.dat",
"harmonic.dat",
],
"lsdyna_cylinder_plate": [
"lsdyna_job.py",
"cylinder_plate.k",
"postprocess.cfile",
],
"python_two_bar_truss_problem": [
"project_setup.py",
"exec_python.py",
"evaluate.py",
"input_parameters.json",
],
"fluent_2d_heat_exchanger": [
"project_setup.py",
"heat_exchanger.jou",
"heat_exchanger.cas.h5",
],
"fluent_nozzle": [
"project_setup.py",
"solve.jou",
"nozzle.cas",
],
"cfx_static_mixer": [
"project_setup.py",
"exec_cfx.py",
"runInput.ccl",
"StaticMixer_001.cfx",
"StaticMixer_001.def",
],
}
SOURCE_DIR = Path(app.srcdir)
ROOT_PATH = SOURCE_DIR.parent.parent

# Create zip files for each example
build_path = ROOT_PATH / "build"
build_path.mkdir(exist_ok=True)
for name, files in EXAMPLES.items():
with ZipFile(build_path / f"{name}.zip", "w") as zip_archive:
for file in files:
zip_archive.write(ROOT_PATH / "examples" / name / file, file)

with ZipFile(build_path / "pyhps_examples.zip", "w") as zip_archive:
for name, files in EXAMPLES.items():
for file in files:
zip_archive.write(ROOT_PATH / "examples" / name / file, Path(name) / file)

# Copy zipped example files to target directory at build time
download_files_dir = SOURCE_DIR.parent / "_build" / "html" / "_downloads"
download_files_dir.mkdir(exist_ok=True)
for file_path in build_path.glob("*"):
if file_path.is_file():
shutil.copy(file_path, DOWNLOAD_FILES_DIR)
shutil.copy(file_path, download_files_dir)


def setup(app: sphinx.application.Sphinx) -> None:
Expand All @@ -365,4 +425,4 @@ def setup(app: sphinx.application.Sphinx) -> None:
Sphinx application instance containing the all the doc build configuration.
"""

app.connect("builder-inited", copy_download_files_to_source_dir)
app.connect("builder-inited", archive_examples)
moe-ad marked this conversation as resolved.
Show resolved Hide resolved
7 changes: 4 additions & 3 deletions tox.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ deps =
-e .[doc]
allowlist_externals = make
commands =
python archive_examples.py
make -C doc html
make -C doc pdf
sphinx-build -M html "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto
sphinx-build -M latex "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto
cd "{toxinidir}/doc/_build/latex" && latexmk -r latexmkrc -pdf *.tex -interaction=nonstopmode || true
moe-ad marked this conversation as resolved.
Show resolved Hide resolved
(test -f "{toxinidir}/doc/_build/latex/*.pdf" && echo pdf exists) || exit 1
Loading