From 1970ce7a1a44eaddf182cdb5a2b7d56efced80f1 Mon Sep 17 00:00:00 2001 From: Jonathan Shimwell Date: Thu, 2 May 2024 11:41:33 +0100 Subject: [PATCH] Sphinx based docs with CI action to build and hosted on gh-pages (#119) * started rtd * testing docs action * update pip * corrected python version * added s to docs * publish every time * added static folder * skipping ci for non code files * changed to rerad the docs theme * started install section * added more sections * added api class * docs ci using conda * added -y for freecad * trying py 3.12 * mimic working conda ci * using rst so no markdown convertion needed * added github edit link * removed path prints * added readme link, badge * format --- .github/workflows/ci.yml | 6 + .github/workflows/documentation.yml | 50 ++++++++ .github/workflows/python-publish.yml | 2 +- .gitignore | 3 + README.md | 6 +- docs/Makefile | 20 ++++ docs/conf.py | 67 +++++++++++ docs/developer_guide.rst | 4 + docs/index.rst | 20 ++++ docs/install.rst | 172 +++++++++++++++++++++++++++ docs/make.bat | 35 ++++++ docs/methodology.rst | 4 + docs/python_api.rst | 10 ++ docs/usage.rst | 29 +++++ pyproject.toml | 6 + src/geouned/GEOUNED/__init__.py | 145 +++++++++++----------- 16 files changed, 505 insertions(+), 74 deletions(-) create mode 100644 .github/workflows/documentation.yml create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/developer_guide.rst create mode 100644 docs/index.rst create mode 100644 docs/install.rst create mode 100644 docs/make.bat create mode 100644 docs/methodology.rst create mode 100644 docs/python_api.rst create mode 100644 docs/usage.rst diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 82493ff6..1710496d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,6 +5,12 @@ on: branches: - dev - main + paths-ignore: + - "**.md" + - "**.txt" + - "**.cff" + - 'docs/**' + - '.gitignore' push: branches: - main diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..f4452b9f --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,50 @@ +name: documentation + +on: + pull_request: + branches: + - dev + - main + push: + branches: + - main + +permissions: + contents: write + +jobs: + testing: + name: Documentation + runs-on: "ubuntu-latest" + defaults: + run: + shell: bash -el {0} + strategy: + matrix: + python-version: ["3.11"] + steps: + - name: checkout actions + uses: actions/checkout@v4 + - uses: conda-incubator/setup-miniconda@v3 + with: + auto-update-conda: true + python-version: ${{ matrix.python-version }} + channels: conda-forge + + - name: install dependencies + run: conda install -c conda-forge freecad -y + + - name: install package + run: | + pip install --upgrade pip + pip install .[docs] + - name: Sphinx build + run: | + sphinx-build docs _build + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: _build/ + force_orphan: true diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index 390560bb..65ec8c99 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -1,4 +1,4 @@ -name: Upload Python Package +name: PyPI Python Package on: release: diff --git a/.gitignore b/.gitignore index 5491c4c7..72c1f57c 100644 --- a/.gitignore +++ b/.gitignore @@ -173,6 +173,9 @@ Warning_Solids_definition.txt .vscode **/__pycache__ + +# documentation +_build docs/source/_build/** docs/build/** docs/source/_autosummary/* diff --git a/README.md b/README.md index b3891821..26642e64 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ [![CI testing](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/ci.yml) - [![Upload Python Package](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/python-publish.yml/badge.svg)](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/python-publish.yml) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/psf/black) +[![documentation](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/documentation.yml/badge.svg)](https://github.com/GEOUNED-org/GEOUNED/actions/workflows/documentation.yml) + +:book: [Documentation](https://GEOUNED-org.github.io/GEOUNED/python_api.html) + # GEOUNED A tool to convert from CAD to CSG & CSG to CAD for Monte Carlo transport codes (MCNP & OpenMC). diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +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 + +# 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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..4af84bb2 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,67 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("../../src")) + +# -- Project information ----------------------------------------------------- + +project = "GEOUNED" +copyright = "2024, UNED" +author = "Juan-Pablo Catalan and Patrick Sauvan" + +# The full version, including alpha/beta/rc tags +release = "1.0.1" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx_autodoc_typehints", + "sphinx.ext.coverage", + "sphinx.ext.napoleon", + "sphinx.ext.doctest", + "sphinx.ext.viewcode", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# 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", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +html_context = { + "display_github": True, +} +# html_favicon = "favicon.ico" diff --git a/docs/developer_guide.rst b/docs/developer_guide.rst new file mode 100644 index 00000000..555da6f9 --- /dev/null +++ b/docs/developer_guide.rst @@ -0,0 +1,4 @@ +Developer guide +=============== + +TOOD \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..3c4cd3d3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. GEOUNED documentation master file, created by + sphinx-quickstart on Tue Apr 30 09:47:11 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +GEOUNED +======= + +GEOUNED converts CAD to Constructive Solid Geometry (CSG) formats for use in +Monte Carlo transport codes. +Supported codes include OpenMC, PHITS, Serpent and MCNP. + +.. toctree:: + :maxdepth: 2 + + install + usage + python_api + methodology + developer_guide diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 00000000..0970f8a0 --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,172 @@ +Install +======= + +There are several options for installing GEOUNED package. +The installation selected has implications for how you run GEOUNED Python scripts. +Currently the Mamba / Conda install is the recommended method. +The main difficulty in installing GEOUNED is integration between the main dependnacy (FreeCAD) and the users system Python. +Mamba / Conda provides the a connection between the FreeCAD Python library and your system Python. +Users have had success installing FreeCAD and making use of the FreeCAD Python as well so these installation methods are listed for completeness. + + +Linux +----- + +Mamba +~~~~~ + +First we need to install a Mamba distribution. There are a few options but here we opt for Miniforge3 as it includes Mamba. + +You can follow the install instructions for `Miniforge3 here `_ or follows the commands below. +Download + +.. code-block:: sh + + curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh" + bash Miniforge3-$(uname)-$(uname -m).sh + +Install Miniforge3 + +.. code-block:: sh + + bash Miniforge3-Linux-x86_64.sh + + +Activate the base environment in your current terminal + +.. code-block:: sh + + mamba activate + + +It is recommended to create a new environment + +.. code-block:: sh + + mamba create --name new_new python=3.11 + + +Activate the new environment + +.. code-block:: sh + + mamba activate new_new + +We have aspirations to create a conda-forge package which will combine these final two steps, but for now FreeCAD and GEOUNED can be installed in two commands. +Install FreeCAD which is the main dependency + +.. code-block:: sh + + mamba install -c conda-forge freecad + + +Install GEOUNED with pip + +.. code-block:: sh + + pip install git+https://github.com/GEOUNED-code/GEOUNED.git + +Then you will be able to run import GEOUNED from within Python + +.. code-block:: python + + import geouned + +Conda +~~~~~ + +First we need to install a Conda distribution. There are a few options but we here we opt for [MiniConda3](https://docs.anaconda.com/free/miniconda/) as it downloads quicker than the fuller [AnaConda](https://www.anaconda.com/download). + +You can follow the install instructions for [MiniConda3 here](https://docs.anaconda.com/free/miniconda/) or follow the commands below. +Download. + +.. code-block:: sh + + mkdir -p ~/miniconda3 + wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh + +Install MiniConda3 + +.. code-block:: sh + + bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3 + + +Activate the base environment in your current terminal + +.. code-block:: sh + + ~/miniconda3/bin/conda init bash + + +It is recommended to create a new environment + +.. code-block:: sh + + conda create --name new_new python=3.11 + + +Activate the new environment + +.. code-block:: sh + + conda activate new_new + +We have aspirations to create a conda-forge package which will combine these final two steps, but for now FreeCAD and GEOUNED can be installed in two commands. +Install FreeCAD which is the main dependency + +.. code-block:: sh + + conda install -c conda-forge freecad + + +Install GEOUNED with pip + +.. code-block:: sh + + pip install git+https://github.com/GEOUNED-code/GEOUNED.git + +Then you will be able to run import GEOUNED from within Python + +.. code-block:: python + + import geouned + +Apt-get +~~~~~~~ + +Snap +~~~~ + +AppImage +~~~~~~~~ + +Mac +--- + + +Mamba +~~~~~ + +Conda +~~~~~ + +Brew +~~~~ + + +Windows +------- + +Mamba +~~~~~ + +Conda +~~~~~ + +Portable FreeCAD installer +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Windows Subsystem for Linux (WSL) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..153be5e2 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/methodology.rst b/docs/methodology.rst new file mode 100644 index 00000000..0631ebcf --- /dev/null +++ b/docs/methodology.rst @@ -0,0 +1,4 @@ +Methodology +=========== + +TODO \ No newline at end of file diff --git a/docs/python_api.rst b/docs/python_api.rst new file mode 100644 index 00000000..c8b1e733 --- /dev/null +++ b/docs/python_api.rst @@ -0,0 +1,10 @@ +Python API reference +==================== + + +.. currentmodule:: geouned + +.. autoclass:: CadToCsg + :members: + :show-inheritance: + diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 00000000..6440d822 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,29 @@ +Usage +===== + +GEOUNED can be used as a Python package or via the command line. + +Python package usage +-------------------- + +The Python API has two main classes. +The first main class is ``CadToCsg()`` which converts CAD geometry to Constructive Solid Geometry (CSG). +There are many arguments that can be passed into the ``CadToCsg()`` class which are documented in the Python API section. +The most minimal use case below shows GEOUNED being imported and the CadToCsg being used to convert a STEP CAD file called 'cuboid.stp' into a varity of CSG format. +If you have install GEOUNED and FreeCAD into your system PYthon then you can simply run a .py script with python. + + +.. code-block:: python + + import geouned + geo = geouned.CadToCsg( + step_file = 'cuboid.stp', + out_formats = ['openMC_XML', 'openMC_PY', 'PHITS', 'Serpent', 'MCNP'] + ) + geo.start() + + +Command line usage +------------------ + +TODO \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 644db16a..7a73526c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,3 +31,9 @@ tests = [ "pytest", "black==24.4.2", ] +docs = [ + "sphinx", + "sphinx_rtd_theme", + "sphinx_autodoc_typehints", + "sphinx_rtd_theme", +] diff --git a/src/geouned/GEOUNED/__init__.py b/src/geouned/GEOUNED/__init__.py index ed66cbd5..0edd6c0f 100644 --- a/src/geouned/GEOUNED/__init__.py +++ b/src/geouned/GEOUNED/__init__.py @@ -25,6 +25,78 @@ class CadToCsg: + """Base class for the conversion of CAD to CSG models + + Args: + title (str, optional): Title of the model. Defaults to "Geouned + conversion". + stepFile (str, optional): Name of the CAD file (in STEP format) to + be converted. Defaults to "". + geometryName (str, optional): Base name of the output file(s). + Defaults to "". + matFile (str, optional): _description_. Defaults to "". + outFormat (typing.Tuple[str], optional): Format for the output + geometry. Available format are: mcnp, openMC_XML, openMC_PY, + phits and serpent. Several output format can be written in the + same geouned run. Defaults to ("mcnp",). + voidGen (bool, optional): Generate voids of the geometry. Defaults + to True. + debug (bool, optional): Write step files of original and decomposed + solids, for each solid in the STEP file. Defaults to False. + compSolids (bool, optional): Join subsolids of STEP file as a single + compound solid. Step files generated with SpaceClaim have not + exactly the same level of solids as FreeCAD. It may a happened + that solids defined has separated solids are read by FreeCAD + as a single compound solid (and will produce only one MCNP + cell). In this case compSolids should be set to False. Defaults + to True. + volSDEF (bool, optional): Write SDEF definition and tally of solid + cell for stochastic volume checking. Defaults to False. + dummyMat (bool, optional): Write dummy material definition card in + the MCNP output file for all material labels present in the + model. Dummy material definition is "MX 1001 1". Defaults to + False. + volCARD (bool, optional): Write the CAD calculated volume in the + cell definition using the VOL card. Defaults to True. + UCARD (_type_, optional): Write universe card in the cell definition + with the specified universe number (if value = 0 Universe card + is not written). Defaults to None. + simplify (str, optional): Simplify the cell definition considering + relative surfaces position and using Boolean logics. Available + options are: "no" no optimization, "void" only void cells are + simplified. Algorithm is faster but the simplification is not + optimal. "voidfull" : only void cells are simplified with the + most optimal algorithm. The time of the conversion can be + multiplied by 5 or more. "full" : all the cells (solids and + voids) are simplified. Defaults to "No". + cellRange (list, optional): Range of cell to be converted (only one + range is allowed, e.g [100,220]). Default all solids are + converted. Defaults to []. + exportSolids (str, optional): Export CAD solid after reading. + The execution is stopped after export, the translation is not + carried out. Defaults to "". + minVoidSize (float, optional): Minimum size of the edges of the + void cell. Units are in mm. Defaults to 200.0. + maxBracket (int, optional): Maximum number of brackets (solid + complementary) allowed in void cell definition. Defaults to 30. + voidMat (list, optional): Assign a material defined by the user + instead of void for cells without material definition and the + cells generated in the automatic void generation. The format + is a 3 valued tuple (mat_label, mat_density, mat_description). + Example (100,1e-3,'Air assigned to Void'). Defaults to []. + voidExclude (list, optional): #TODO see issue 87. Defaults to []. + startCell (int, optional): Starting cell numbering label. Defaults to 1. + startSurf (int, optional): Starting surface numbering label. Defaults to 1. + cellCommentFile (bool, optional): Write an additional file with + comment associated to each CAD cell in the MCNP output file. + Defaults to False. + cellSummaryFile (bool, optional): Write an additional file with + information on the CAD cell translated. Defaults to True. + sort_enclosure (bool, optional): If enclosures are defined in the + CAD models, the voids cells of the enclosure will be located in + the output file in the same location where the enclosure solid + is located in the CAD solid tree.. Defaults to False. + """ def __init__( self, @@ -54,78 +126,7 @@ def __init__( cellSummaryFile: bool = True, sort_enclosure: bool = False, ): - """Base class for the conversion of CAD to CSG models - - Args: - title (str, optional): Title of the model. Defaults to "Geouned - conversion". - stepFile (str, optional): Name of the CAD file (in STEP format) to - be converted. Defaults to "". - geometryName (str, optional): Base name of the output file(s). - Defaults to "". - matFile (str, optional): _description_. Defaults to "". - outFormat (typing.Tuple[str], optional): Format for the output - geometry. Available format are: mcnp, openMC_XML, openMC_PY, - phits and serpent. Several output format can be written in the - same geouned run. Defaults to ("mcnp",). - voidGen (bool, optional): Generate voids of the geometry. Defaults - to True. - debug (bool, optional): Write step files of original and decomposed - solids, for each solid in the STEP file. Defaults to False. - compSolids (bool, optional): Join subsolids of STEP file as a single - compound solid. Step files generated with SpaceClaim have not - exactly the same level of solids as FreeCAD. It may a happened - that solids defined has separated solids are read by FreeCAD - as a single compound solid (and will produce only one MCNP - cell). In this case compSolids should be set to False. Defaults - to True. - volSDEF (bool, optional): Write SDEF definition and tally of solid - cell for stochastic volume checking. Defaults to False. - dummyMat (bool, optional): Write dummy material definition card in - the MCNP output file for all material labels present in the - model. Dummy material definition is "MX 1001 1". Defaults to - False. - volCARD (bool, optional): Write the CAD calculated volume in the - cell definition using the VOL card. Defaults to True. - UCARD (_type_, optional): Write universe card in the cell definition - with the specified universe number (if value = 0 Universe card - is not written). Defaults to None. - simplify (str, optional): Simplify the cell definition considering - relative surfaces position and using Boolean logics. Available - options are: "no" no optimization, "void" only void cells are - simplified. Algorithm is faster but the simplification is not - optimal. "voidfull" : only void cells are simplified with the - most optimal algorithm. The time of the conversion can be - multiplied by 5 or more. "full" : all the cells (solids and - voids) are simplified. Defaults to "No". - cellRange (list, optional): Range of cell to be converted (only one - range is allowed, e.g [100,220]). Default all solids are - converted. Defaults to []. - exportSolids (str, optional): Export CAD solid after reading. - The execution is stopped after export, the translation is not - carried out. Defaults to "". - minVoidSize (float, optional): Minimum size of the edges of the - void cell. Units are in mm. Defaults to 200.0. - maxBracket (int, optional): Maximum number of brackets (solid - complementary) allowed in void cell definition. Defaults to 30. - voidMat (list, optional): Assign a material defined by the user - instead of void for cells without material definition and the - cells generated in the automatic void generation. The format - is a 3 valued tuple (mat_label, mat_density, mat_description). - Example (100,1e-3,'Air assigned to Void'). Defaults to []. - voidExclude (list, optional): #TODO see issue 87. Defaults to []. - startCell (int, optional): Starting cell numbering label. Defaults to 1. - startSurf (int, optional): Starting surface numbering label. Defaults to 1. - cellCommentFile (bool, optional): Write an additional file with - comment associated to each CAD cell in the MCNP output file. - Defaults to False. - cellSummaryFile (bool, optional): Write an additional file with - information on the CAD cell translated. Defaults to True. - sort_enclosure (bool, optional): If enclosures are defined in the - CAD models, the voids cells of the enclosure will be located in - the output file in the same location where the enclosure solid - is located in the CAD solid tree.. Defaults to False. - """ + self.title = title self.stepFile = stepFile self.geometryName = geometryName