Merge dev into main

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[Feature request] - title of the issue"
+labels: enhancement
+assignees: ''
+
+---
+
+# Is your feature request related to a problem? Please describe.
+A clear and concise description of what the problem is.
+
+# Describe the solution you'd like
+A clear and concise description of what you want to happen.
+
+# Describe alternatives you've considered
+A clear and concise description of any alternative solutions or features you've considered.
+
+# Additional context
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/improve_documentation.md

@@ -0,0 +1,23 @@
+---
+name: Improve documentation
+about: Help us improve our documentation
+title: "[DOC] - title of the issue"
+labels: documentation
+assignees: ''
+
+---
+
+# What were you looking for
+Please try to describe in a concise way which kind of information you were looking for and where were you looking.
+
+# Is the information available in the doc but not where you would expect?
+let us know if you ended up finding the information you were looking for in another (unexpected) section of the doc.
+
+# Is information completely lacking or partial?
+please specify if you are asking for better explanation/clarification of the text or if the information is completely lacking.
+
+# Where would you insert the missing information?
+describe here where you would put the information.
+
+# Additional context
+you can use this space to give any other additional information that you think would be useful to solve the issue.

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+If you are a first-time contributor to GEOUNED, please read our contributing guidelines:
+https://github.com/GEOUNED-org/GEOUNED/blob/main/CONTRIBUTING.md
+
+# Description
+
+Please include a summary of the changes and motivation for the changes
+
+# Fixes issue
+
+Please link to any issues that this PR fixes
+
+# Checklist
+
+- [ ] I'm making a PR from a feature branch on my fork into GEOUNED-org/GEOUNED/dev branch
+- [ ] I have followed [PEP8 style guide]([url](https://peps.python.org/pep-0008/)) for Python or run a formatter such as [black]([url](https://github.com/psf/black)) or [ruff format]([url](https://github.com/astral-sh/ruff)) on my code
+- [ ] I have made corresponding changes to the documentation
+- [ ] I have added tests that prove my fix is effective or that my feature works

.github/workflows/black.yml

@@ -0,0 +1,12 @@
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: psf/black@stable
+        with:
+          version: "24.4.2"

.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
       branches:
         - dev
         - main
+      paths-ignore:
+        - "**.md"
+        - "**.txt"
+        - "**.cff"
+        - 'docs/**'
+        - '.gitignore'
     push:
       branches:
         - main
@@ -44,13 +50,17 @@ jobs:
           run: |
             python -m pip install --upgrade pip
             python -m pip install .
+            geouned_cadtocsg --help
             python -c 'import geouned'
-            python -c 'from geouned import GEOUNED'
+            python -c 'from geouned import CadToCsg'
             python -c 'from geouned.GEOReverse import reverse'
             python -m pip install .[tests]
 
         - name: testing GEOUNED functionality
-          run: python -m pytest -v tests/test_convert.py
+          run: |
+            python -m pytest -v tests/test_convert.py
+            geouned_cadtocsg -i tests/config_complete_defaults.json
+            geouned_cadtocsg -i tests/config_non_defaults.json
 
         - name: install openmc
           if: ${{ matrix.os == 'ubuntu-latest'}}

.github/workflows/documentation.yml

@@ -0,0 +1,52 @@
+name: documentation
+
+on:
+  pull_request:
+    branches:
+      - dev
+      - main
+  push:
+    branches:
+      - main
+      - dev
+
+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
+        if: github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.github/workflows/python-publish.yml

@@ -1,4 +1,4 @@
-name: Upload Python Package
+name: PyPI Python Package
 
 on:
   release:

.gitignore

@@ -166,8 +166,16 @@ cython_debug/
 # testing folder
 tests_outputs/
 
+# debug output folders
+fuzzySurfaces
+Suspicious_solids/
+Warning_Solids_definition.txt
+
 .vscode
 **/__pycache__
+
+# documentation
+_build
 docs/source/_build/**
 docs/build/**
 docs/source/_autosummary/*

README.md

@@ -1,82 +1,14 @@
 [![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)
+
 
 # GEOUNED
 A tool to convert from CAD to CSG & CSG to CAD for Monte Carlo transport codes (MCNP & OpenMC).
 This repository contains the implementation of the algorithm presented in the paper [GEOUNED: A new conversion tool from CAD to Monte Carlo geometry](https://doi.org/10.1016/j.net.2024.01.052).
 
-## Installation 
-
-Install directly from the repository (for python versions > 3.7 => FreeCAD >= 0.19 ):
-
-```bash
-pip install git+https://github.com/GEOUNED-code/GEOUNED.git
-```
-
-Otherwise, the source code included in the ~src/ folder can be directly downloaded and properly reached by path variable as follows:
-
-```python
-import sys
-GEO_path='the path in your local computer'
-sys.path.append('GEO_path')
-``` 
-
-the same should be made for FreeCAD libraries. You can also define appropriately the PYTHONPATH variable for both modules. 
-
-If you are using FreeCAD in windows there is included a python distribution within FreeCAD distribution (by default located in C:\Program Files\FreeCAD 0.XX\bin\).
-In that case you can install directly de module using:
-
-```bash
-C:\Program Files\FreeCAD 0.XX\bin\python.exe -m pip install git+https://github.com/GEOUNED-code/GEOUNED.git
-```
-using this option you have directly access to both FreeCAD and GEOUNED python modules. 
-Furthermore, using this python compatibilities problems between different versions of python are avoided (some dynamic libraries of FreeCAD depends on the version of python used during the built process). 
-
-## How to use
-
-The code is used via python scripting.  
-
-The first step is to call the python modules of both FreeCAD and GEOUNED (this can be avoided if you have installed GEOUNED as commented in the previous section and using the python distributed with FreeCAD).
-
-```python
-import sys
-GEO_path='the path in your local computer, the complete or relative path to the ~src/ folder'
-FreeCAD_path='path of FreeCAD python modules'
-sys.path.append(GEO_path)
-sys.path.append(FreeCAD_path)
-``` 
-The second step is to call or GEOUNED for CAD to CSG conversion or GEOReverse for CSG to CAD.
-
-From CAD to CSG:
-
-```python
-from geouned import GEOUNED
-inifile='Name of config file for forward conversion'
-GEO = GEOUNED(inifile)
-GEO.SetOptions()
-GEO.Start()
-``` 
-From CSG to CAD (so far only for MCNP): 
-
-```python
-from GEOReverse.reverse import reverse
-inifile='Name of config file for reverse conversion'
-reverse(inifile)
-``` 
-In the ~scripts/ folder you can find a script (geouned for linux or geouned.py for windows) to call both modules directly by command line as follows:
-
-windows (forward and reverse):
-```bash
-/~>python geouned.py file_config_name
-/~>python geouned.py -r file_config_name
-```
-
-linux (forward and reverse):
-```bash
-/~>geouned file_config_name
-/~>geouned -r file_config_name
-```
-
-Detailed descriptions of all options of the config files (forward and reverse) are given in the manual located in ~docs/ folder.
+See the [online documentation](https://geouned-org.github.io/GEOUNED/index.html) for installation, usage and API reference.
 
 ## Citation
 

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)

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"

docs/developer_guide.rst

@@ -0,0 +1,4 @@
+Developer guide
+===============
+
+TOOD

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: 3
+
+   install/index
+   usage/index
+   python_api
+   methodology
+   developer_guide