diff --git a/.gitignore b/.gitignore index 4d3bc917..6c154d9f 100644 --- a/.gitignore +++ b/.gitignore @@ -52,3 +52,5 @@ __pycache__/ # PyCharm .idea/ +# Sphinx documentation +documentation/_build/ \ No newline at end of file diff --git a/documentation/building.rst b/documentation/building.rst index 2fde890e..cd21a1dd 100644 --- a/documentation/building.rst +++ b/documentation/building.rst @@ -57,14 +57,14 @@ For installing the packages required for building the documentation with Sphinx: Windows ======= +Install the following requirements: -On Windows, Visual Studio is the recommended toolchain with the Intel fortran compiler. -CMake is readily available and a binary is supplied on the CMake `download page `_. -SWIG 4.0 is available from the SWIG `download page `_. -The latest release at this time is version 4.0.2. -For Sphinx you will first need to have Python installed, which is required when creating the Python bindings anyway. -Python 3.9 works well with Visual Studio 2017 when building Python extension libraries (which is what the bindings are when used from Python). -Python 3.9 is availble from the Python `download page `_. +* **Git**: `download page `_ +* **Python**: `download page `_. Select the add to path option +* **CMake**: `download page `_. Select the add to path option +* **SWIG**: `download page `_. Extract and put in your Program Files (x86) directory, e.g.: C:\\Program Files (x86)\\SWIG\\swigwin-4.1.1 +* **Visual Studio**: `download page `_. (The community version is free). Install with C++ desktop development. Add the IDE folder to your Path environment variable, e.g.: C:\\Program Files\\Microsoft Visual Studio\\2022\\Community\\Common7\\IDE +* **Intel Fortran Compiler**: `download page `_. Select the integrate with Visual Studio option. macOS ===== @@ -85,6 +85,7 @@ GNU/Linux The package manager for the distro will (most likely) have the required packages to install. Before installing check to see if any of the requirements are already available:: + git --version gfortran --version cmake --version python --version @@ -93,10 +94,12 @@ Before installing check to see if any of the requirements are already available: In the case of the python package we require the *development* package for python this must be installed for the python bindings to become available. For the Ubuntu distribution you can get the missing packages with the following commands:: - sudo apt-get install gfortran - sudo apt-get install cmake - sudo apt-get install pythonX.Y-dev # Where X and Y are the major and minor version numbers of the Python you want to install, any version above 3.7 will work - sudo apt-get install swig + sudo apt install git + sudo apt install python3-dev + sudo apt install python-is-python3 + sudo apt install cmake + sudo apt install gfortran + sudo apt install swig ----- CMake @@ -171,6 +174,13 @@ From the terminal change into the 'lungsim' directory, then run the **make** com .. note:: Not recently checked to see if this is still working. + +.. _IntelFortranCompilerDownload: https://www.intel.com/content/www/us/en/developer/tools/oneapi/hpc-toolkit-download.html + +.. _VisualStudioDownload: https://visualstudio.microsoft.com/downloads/ + +.. _GitDownload: https://git-scm.com/downloads + .. _CMakeDownload: https://cmake.org/download .. _SWIGDownload: http://www.swig.org/download.html diff --git a/documentation/conf.py b/documentation/conf.py index bc855d5c..11bebe07 100755 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -36,7 +36,9 @@ 'sphinx.ext.ifconfig', 'sphinxfortran.fortran_domain', 'sphinxfortran.fortran_autodoc', + 'sphinx.ext.autosectionlabel' ] +autosectionlabel_prefix_document = True # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -53,7 +55,7 @@ master_doc = 'index' # General information about the project. -project = 'Ventilation' +project = 'Aether' copyright = '2022, Lung Group ABI' author = 'Lung Group ABI' @@ -81,7 +83,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ["_build"] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -167,9 +169,9 @@ # Custom sidebar templates, maps document names to template names. #html_sidebars = {} -html_sidebars = { - '**': ['localtoc.html', 'forksidebar.html', 'sourcelink.html', 'searchbox.html'], -} +# html_sidebars = { +# '**': ['localtoc.html', 'forksidebar.html', 'sourcelink.html', 'searchbox.html'], +# } # Additional templates that should be rendered to pages, maps page names to # template names. diff --git a/documentation/welcome.rst b/documentation/welcome.rst new file mode 100644 index 00000000..bfaa464e --- /dev/null +++ b/documentation/welcome.rst @@ -0,0 +1,58 @@ +.. Auckland Bioengineering Lung Simulator master file, created by + Alys Clark on Fri 18 March 2016. + +======================================== +Welcome to the documentation for Aether! +======================================== + +Hello everyone! Welcome to the documentation for our lung code! + +The first thing we need to do to get going using this code is to :doc:`acquire ` it then we can :doc:`build ` the aether library. +Once we have built the library we can :doc:`run ` it. +Before you start to develop the code make sure you read the section on :doc:`testing `. +Lastly, before you ask to get your code merged make sure you have looked at the :doc:`modules ` and :doc:`fortran styles ` sections to ensure that you have followed the conventions for this codebase. + +Thanks and enjoy! + +Quick Start +=========== +Install the requirements for :ref:`building:GNU/Linux` or :ref:`building:Windows` + +If you have all the requirements for building the aether libraries and bindings then the following commands are a quick description on how to get setup and using the library, for further information or clarification read the full documentation. + +Quick start instructions for GNU/Linux and macOS + +(bash):: + + git clone https://github.com/LungNoodle/lungsim.git + python -m venv venv-aether + source venv-aether/bin/activate + pip install --upgrade pip + pip install numpy + here=$(pwd) + cmake -S lungsim -B build-lungsim -D Python_EXECUTABLE=$here/venv-aether/bin/python + cd build-lungsim + make + pip install -e src/bindings/python + python ../lungsim/.github/scripts/diagnostics_test.py + +Quick start instructions for Windows + +(Note: replace paths for -D SWIG_EXECUTABLE and -D SWIG_DIR with the relevant paths for your SWIG install) + +(cmd):: + + git clone https://github.com/LungNoodle/lungsim.git + python -m venv venv-aether + python -m pip install --upgrade pip + venv-aether\Scripts\activate + pip install numpy + cmake -S lungsim -B build-lungsim -D Python_EXECUTABLE=%cd%/venv-aether/Scripts/python -D SWIG_EXECUTABLE="C:/Program Files (x86)/SWIG/swigwin-4.1.1/swig.exe" -D SWIG_DIR="C:/Program Files (x86)/SWIG/swigwin-4.1.1/lib" + cd build-lungsim + cmake --build . --config Release + pip install -e src\bindings\python\Release + python ..\lungsim\.github\scripts\diagnostics_test.py + + + +If all is successful, the final command should run a test python script with the output "test succeeded". \ No newline at end of file