sas.sascalc.doc_regen package

Submodules

sas.sascalc.doc_regen.makedocumentation module

Creates documentation from .py files

sas.sascalc.doc_regen.makedocumentation.call_all_files()

A master method to regenerate all known documentation.

sas.sascalc.doc_regen.makedocumentation.call_one_file(file: Path | str | PathLike)

A master method to regenerate a single file that is passed to the method.

Parameters:

file – A file name that needs the html regenerated.

sas.sascalc.doc_regen.makedocumentation.call_regenmodel(filepaths: list[Path | str | PathLike])

Runs regenmodel.py or regentoc.py (specified in parameter regen_py) with all found PY_FILES.

Parameters:

filepath – A file-path like object or list of file-path like objects to regenerate.

Return removed_files:

A list of src files that were removed during the regeneration process.

sas.sascalc.doc_regen.makedocumentation.create_user_files_if_needed()

Create user documentation directories if necessary and copy built docs there.

sas.sascalc.doc_regen.makedocumentation.generate_html(single_files: Path | str | PathLike | list[Path | str | PathLike] = '', rst: bool = False, output_path: Path | str | PathLike = '')

Generates HTML from an RST using a subprocess. Based off of syntax provided in Makefile found in /sasmodels/doc/

Parameters:

  • single_file – A file name that needs the html regenerated. NOTE: passing in this parameter will result in ONLY the specified file being regenerated. The TOC will not be updated correctly, and as such, this arg should only be passed when ‘preview’ documentation generation is supported in a later version.

  • rst – Boolean to declare the rile an rst-like file.

sas.sascalc.doc_regen.makedocumentation.get_main_docs() → list[Path | str | PathLike]

Generates a list of all .py files to be passed into compiling functions found in the main source code, as well as in the user plugin model directory.

Returns:

A list of python files

sas.sascalc.doc_regen.makedocumentation.get_py(directory: Path | str | PathLike) → list[Path | str | PathLike]

Find all python files within a directory that are meant for sphinx and return those file-paths as a list.

Parameters:

directory – A file path-like object to find all python files contained there-in.

Returns:

A list of python files found.

sas.sascalc.doc_regen.makedocumentation.make_documentation(target: Path | str | PathLike = '.') → Popen

Similar to call_one_file, but will fall back to calling all files and regenerating everything if an error occurs.

Parameters:

target – A file name that needs the html regenerated.

sas.sascalc.doc_regen.makedocumentation.sync_plugin_models()

Remove deleted plugin models from source-temp/user/models/src/

sas.sascalc.doc_regen.regenmodel module

Generate ReST docs with figures for each model.

usage: python genmodels.py path/to/model1.py …

Output is placed in the directory model, with model1.py producing model/model1.rst and model/img/model1.png.

Set the environment variable SASMODELS_BUILD_CACHE to the path for the build cache. That way the figure will only be regenerated if the kernel code has changed. This is useful on a build server where the environment is created from scratch each time. Be sure to clear the cache from time to time so it doesn’t get too large. Also, the cache will need to be cleared if the image generation is updated, either because matplotib is upgraded or because this file changes. To accomodate both these conditions set the path as the following in your build script:

SASMODELS_BUILD_CACHE=/tmp/sasbuild_$(shasum genmodel.py | cut -f 1 -d" ")

Putting the cache in /tmp allows temp-reaper to clean it up automatically. Putting the sha1 hash of this file in the cache directory name means that a new cache will be created whenever the text of this file has changed, even if it is downloaded from a different branch of the repo.

The release build should not use any caching.

This program uses multiprocessing to build the jobs in parallel. Use the following:

SASMODELS_BUILD_CPUS=0  # one per processor
SASMODELS_BUILD_CPUS=1  # don't use multiprocessing
SASMODELS_BUILD_CPUS=n  # use n processes

Note that sasmodels with OpenCL is very good at using all the processors when generating the model plot, so you should only use a small amount of parallelism (maybe 2-4 processes), allowing matplotlib to run in parallel. More parallelism won’t help, and may overwhelm the GPU if you have one.

sas.sascalc.doc_regen.regenmodel.copy_file(src: str, dst: str)

Copy from src to dst, making the destination directory if needed.

Parameters:

  • src – The original file name to be copied.

  • dst – The destination to copy the file.

sas.sascalc.doc_regen.regenmodel.copy_if_newer(src: str, dst: str)

Copy from src to dst if src is newer or dst doesn’t exist.

sas.sascalc.doc_regen.regenmodel.figfile(model_info: ModelInfo) → str

Generates a standard file name for generated model figures based on the model info.

sas.sascalc.doc_regen.regenmodel.gen_docs(model_info: ModelInfo, outfile: str)

Generate the doc string with the figure inserted before the references.

Add link to model sources from the doc tree.

sas.sascalc.doc_regen.regenmodel.main()

Process files listed on the command line via process_model().

sas.sascalc.doc_regen.regenmodel.make_figure(model_info: ModelInfo, opts: Dict[str, Any])

Generate the figure file to include in the docs.

sas.sascalc.doc_regen.regenmodel.make_figure_cached(model_info: ModelInfo, opts: dict[str, Any])

Cache sasmodels figures between independent builds.

To enable caching, set SASMODELS_BUILD_CACHE in the environment. A (mostly) unique key will be created based on model source and opts. If the png file matching that key exists in the cache it will be copied into the documentation tree, otherwise a new png file will be created and copied into the cache.

Be sure to clear the cache from time to time. Even though the model source

sas.sascalc.doc_regen.regenmodel.newer(src: str, dst: str) → bool

Return a boolean whether the src file is newer than the dst file.

sas.sascalc.doc_regen.regenmodel.plot_1d(model: KernelModel, opts: Dict[str, Any], ax: Axes)

Create a 1-D image based on the model.

sas.sascalc.doc_regen.regenmodel.plot_2d(model: KernelModel, opts: Dict[str, Any], ax: Axes)

Create a 2-D image based on the model.

sas.sascalc.doc_regen.regenmodel.plot_profile_inset(model_info: ModelInfo, ax: Axes)

Plot 1D radial profile as inset plot.

sas.sascalc.doc_regen.regenmodel.process_model(py_file: str, force=False) → str

Generate doc file and image file for the given model definition file.

Does nothing if the corresponding rst file is newer than py_file. Also checks the timestamp on the genmodel.py program (__file__), since we want to rerun the generator on all files if we change this code.

If force then generate the rst file regardless of time stamps.

Parameters:

  • py_file – The python model file that will be processed into ReST using sphinx.

  • force – Regardless of the ReST file age, relative to the python file, force the regeneration.

sas.sascalc.doc_regen.regentoc module

sas.sascalc.doc_regen.regentoc._add_model(file: IO[str], model_name: str)

Add a model file name to an already open file.

sas.sascalc.doc_regen.regentoc._add_subcategory(category_name: str, parent: BinaryIO)

Add a subcategory to a ReST file.

sas.sascalc.doc_regen.regentoc._make_category(category_name: str, label: str, title: str, parent: BinaryIO | None = None) → IO

Generate the base ReST file for a specific model category.

sas.sascalc.doc_regen.regentoc._maybe_make_category(category: str, models: list[str], cat_files: dict[str, BinaryIO], model_toc: BinaryIO)

Add a category to the list of categories, assuming it isn’t already in the list.

sas.sascalc.doc_regen.regentoc.generate_toc(model_files: list[str])

Generate the doc tree and ReST files from a list of model files.

sas.sascalc.doc_regen.regentoc.main(files)

Module contents