Update of the documentation layout (#285)

* update_of_docs * test * update 2 * update 3 * update 4 * test 5 * update 6 * update 7 * update 8 * test materials * test again * final
GEOUNED-org · Dec 9, 2024 · efc249b · efc249b
1 parent bc3829a
commit efc249b
Show file tree

Hide file tree

Showing 23 changed files with 199 additions and 49 deletions.
diff --git a/docs/Training_on_GEOUNED_tool.pdf b/docs/Training_on_GEOUNED_tool.pdf
diff --git a/docs/User_Guide_GEOUNED_v2.0.pdf b/docs/User_Guide_GEOUNED_v2.0.pdf
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,7 +20,6 @@
 
 project = "GEOUNED"
 copyright = "2024, UNED"
-author = "Juan-Pablo Catalan and Patrick Sauvan"
 
 # The full version, including alpha/beta/rc tags
 import geouned
@@ -83,6 +82,6 @@
         "json_url": "https://raw.githubusercontent.com/GEOUNED-org/GEOUNED/dev/docs/version_switcher.json",
         "version_match": version_match,
     },
-    "nav_title": "Geouned",
+    "nav_title": "GEOUNED",
     "navbar_start": ["version-switcher", "navbar-icon-links"],
 }
diff --git a/docs/developer_guide.rst → docs/developers_guide.rst b/docs/developer_guide.rst → docs/developers_guide.rst
@@ -1,4 +1,4 @@
-Developer guide
+Developers guide
 ===============
 
 Developer install with Mamba

diff --git a/docs/images/mat_list.png b/docs/images/mat_list.png
diff --git a/docs/images/mat_tag.png b/docs/images/mat_tag.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,9 +1,4 @@
-.. 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 Documentation
+GEOUNED Documentation
 =====================
 
 **Version**: |version|
@@ -13,10 +8,9 @@ Monte Carlo transport codes.
 Supported codes include OpenMC, PHITS, Serpent and MCNP.
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
-   install/index
-   usage/index
+   quick_install_guide
+   users_guide/index
    python_api
-   methodology
-   developer_guide
+   developers_guide
diff --git a/docs/methodology.rst b/docs/methodology.rst
diff --git a/docs/quick_install_guide.rst b/docs/quick_install_guide.rst
@@ -0,0 +1,112 @@
+Quick Install Guide
+===================
+
+Linux
+~~~~~
+
+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 <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_env python=3.11
+
+
+Activate the new environment
+
+.. code-block:: sh
+
+    conda activate new_env
+
+Install GEOUNED from conda-forge
+
+.. code-block:: sh
+
+    conda install -c conda-forge geouned -y
+
+Then you will be able to run import GEOUNED from within Python
+
+.. code-block:: python
+
+    import geouned
+
+You will also be able to use the GEOUNED command line tool
+
+.. code-block:: bash
+
+    geouned_cadtocsg --help
+
+
+Windows
+~~~~~~~
+
+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 <https://docs.anaconda.com/free/miniconda/>`_ 
+
+Download and execute the Miniforge3 Windows installer
+
+You can get it from the `Miniforge3 GitHub repository here <https://docs.anaconda.com/free/miniconda/>`_ or from the link below
+
+`https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe <https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe>`_
+
+Open "Anaconda Prompt (miniconda3)" which will now be available on your start menu.
+
+It is recommended to create a new environment
+
+.. code-block:: sh
+
+    conda create --name new_env python=3.11
+
+Activate the new environment
+
+.. code-block:: sh
+
+    conda activate new_env
+
+Since one of the GEOUNED dependencies is FreeCAD, classic conda solver of dependencies may significantly slow down the installation. For this reason, it is recommended to install and use conda-libmamba-solver
+
+.. code-block:: sh
+
+    conda install conda-libmamba-solver
+
+Install GEOUNED from conda-forge, forcing the use of libmamba solver
+
+.. code-block:: sh
+
+    conda install -c conda-forge geouned -y --solver=libmamba
+
+Then you will be able to run import GEOUNED from within Python
+
+.. code-block:: python
+
+    import geouned
+
+You will also be able to use the GEOUNED command line tool
+
+.. code-block:: bash
+
+    geouned_cadtocsg --help
diff --git a/docs/usage/index.rst → ...uide/execution_settings/cad2csg/index.rst b/docs/usage/index.rst → ...uide/execution_settings/cad2csg/index.rst
@@ -1,16 +1,11 @@
-.. usage
-
-Usage
-=====
+CAD to CSG Translation
+======================
 
 GEOUNED can be used as a Python package with the API or as a command line tool with the CLI.
 
 
 .. toctree::
-   :numbered:
    :maxdepth: 1
 
    python_cadtocsg_api_usage
    python_cadtocsg_cli_usage
-   python_csgtocad_api_usage
-   python_csgtocad_cli_usage
diff --git a/docs/usage/python_cadtocsg_api_usage.rst → ...ngs/cad2csg/python_cadtocsg_api_usage.rst b/docs/usage/python_cadtocsg_api_usage.rst → ...ngs/cad2csg/python_cadtocsg_api_usage.rst
@@ -1,5 +1,5 @@
-Python Package Usage, CAD to CSG conversion
-===========================================
+Python Package Usage
+====================
 
 The 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 reference section <../python_api.html>`_ of the documentation.

diff --git a/docs/usage/python_cadtocsg_cli_usage.rst → ...ngs/cad2csg/python_cadtocsg_cli_usage.rst b/docs/usage/python_cadtocsg_cli_usage.rst → ...ngs/cad2csg/python_cadtocsg_cli_usage.rst
@@ -1,5 +1,5 @@
-Command Line Tool Usage, CAD to CSG conversion
-==============================================
+Command Line Tool Usage
+=======================
 
 GEOUNED CAD to CSG conversion can be performed in the command line.
 

diff --git a/docs/users_guide/execution_settings/csg2cad/index.rst b/docs/users_guide/execution_settings/csg2cad/index.rst
@@ -0,0 +1,11 @@
+CSG to CAD Translation
+======================
+
+GEOUNED can be used as a Python package with the API or as a command line tool with the CLI.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   python_csgtocad_api_usage
+   python_csgtocad_cli_usage
diff --git a/docs/usage/python_csgtocad_api_usage.rst → ...ngs/csg2cad/python_csgtocad_api_usage.rst b/docs/usage/python_csgtocad_api_usage.rst → ...ngs/csg2cad/python_csgtocad_api_usage.rst
@@ -1,5 +1,5 @@
-Python Package Usage, CSG to CAD conversion
-===========================================
+Python Package Usage
+====================
 
 The main class is ``CsgToCad()`` which converts Constructive Solid Geometry (CSG) to CAD.
 There are a few arguments that can be passed into the ``CsgToCad().export_cad()`` method which are documented in the `Python API reference section <../python_api.html>`_ of the documentation.

diff --git a/docs/usage/python_csgtocad_cli_usage.rst → ...ngs/csg2cad/python_csgtocad_cli_usage.rst b/docs/usage/python_csgtocad_cli_usage.rst → ...ngs/csg2cad/python_csgtocad_cli_usage.rst
@@ -1,5 +1,5 @@
-Command Line Tool Usage, CSG to CAD conversion
-==============================================
+Command Line Tool Usage
+=======================
 
 GEOUNED CSG to CAD conversion can be performed in the command line.
 

diff --git a/docs/users_guide/execution_settings/index.rst b/docs/users_guide/execution_settings/index.rst
@@ -0,0 +1,11 @@
+Execution Settings
+==================
+
+GEOUNED can be used as a Python package with the API or as a command line tool with the CLI.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   cad2csg/index
+   csg2cad/index
diff --git a/docs/users_guide/index.rst b/docs/users_guide/index.rst
@@ -0,0 +1,14 @@
+Users Guide
+===========
+
+GEOUNED can be used as a Python package with the API or as a command line tool with the CLI.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   installation/index
+   execution_settings/index
+   simplification
+   material_allocation
+   void_generation
diff --git a/docs/install/index.rst → docs/users_guide/installation/index.rst b/docs/install/index.rst → docs/users_guide/installation/index.rst
@@ -1,7 +1,5 @@
-.. usage
-
-Install
-=======
+Installation
+============
 
 There are several options for installing GEOUNED package.
 The installation selected has implications for how you run GEOUNED Python scripts.
@@ -12,7 +10,6 @@ Users have also had success installing FreeCAD and making use of the Python vers
 
 
 .. toctree::
-   :numbered:
    :maxdepth: 1
 
    install_linux

diff --git a/docs/install/install_linux.rst → ...sers_guide/installation/install_linux.rst b/docs/install/install_linux.rst → ...sers_guide/installation/install_linux.rst
@@ -62,7 +62,7 @@ You will also be able to use the GEOUNED command line tool
 User install with 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>`_.
+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 <https://docs.anaconda.com/free/miniconda/>`_ or follow the commands below.
 Download.

diff --git a/docs/install/install_windows.rst → ...rs_guide/installation/install_windows.rst b/docs/install/install_windows.rst → ...rs_guide/installation/install_windows.rst
@@ -52,7 +52,7 @@ You will also be able to use the GEOUNED command line tool
 User install with 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>`_.
+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 <https://docs.anaconda.com/free/miniconda/>`_ 
 

diff --git a/docs/users_guide/material_allocation.rst b/docs/users_guide/material_allocation.rst
@@ -0,0 +1,22 @@
+Material Allocation
+===================
+
+The material of the components can be assigned directly in the tree CAD by including a text with _mXX_ within the component name.
+
+.. image:: /images/mat_tag.png
+   :alt: Example of a CAD tree with a _mXX_ tag.
+   :align: center
+   :width: 50%
+
+The material assigned to the corresponding cell should be defined in the material definition file whose name is provided by the matFile keyword.
+This file has the following format:
+
+.. image:: /images/mat_list.png
+   :alt: Example of a material list.
+   :align: center
+   :width: 50%
+
+Where # is used for comments and the rest of the lines specifies the id of the material, the nominal density and the text to be included as a comment.
+The nominal density value is multiplied by -1 so the criterium is inverted with respect to MCNP one (i.e. g/cm3 positive and atm/b/cm negative).
+The nominal density can be changed by the inclusion of a multiplication factor using the following text in the CAD tree _mXX_dXX.XX_.
+For example, in our case _m01_d2.0_ will produce a cell with material 1 and density 2.0.
diff --git a/docs/users_guide/simplification.rst b/docs/users_guide/simplification.rst
@@ -0,0 +1,4 @@
+Simplification of Geometry
+===========================
+
+To be added.
diff --git a/docs/users_guide/void_generation.rst b/docs/users_guide/void_generation.rst
@@ -0,0 +1,4 @@
+Void Generation
+===============
+
+To be added.