Docs

.github/workflows/CD.yml

@@ -1,11 +1,9 @@
 on:
   push:
-    branches:
-      - master
 name: release-please
 jobs:
   continuous-integration:
-    name: Continuous integration ${{ matrix.os }} python ${{ matrix.python-version }} 
+    name: Continuous integration ${{ matrix.os }} python ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -24,22 +22,35 @@ jobs:
         shell: bash -l {0}
         run: |
           conda install -c loop3d --file dependencies.txt -y
-          
+
       - name: Checking formatting of code
         shell: bash -l {0}
         run: |
-            pip install flake8
-            # stop the build if there are Python syntax errors or undefined names
-            flake8 map2loop --count --select=E9,F63,F7,F82 --show-source --statistics
-            # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-            flake8 map2loop --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-      - name: Building and install 
+          pip install flake8
+          # stop the build if there are Python syntax errors or undefined names
+          flake8 map2loop --count --select=E9,F63,F7,F82 --show-source --statistics
+          # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+          flake8 map2loop --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      - name: Building and install
         shell: bash -l {0}
         run: |
           pip install .
-
+  documentation-test:
+    runs-on: ubuntu-latest
+    #needs: continuous-integration
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          cp CHANGELOG.md docs/source/CHANGELOG.md
+          docker build . -t=docs -f docs/Dockerfile 
+          docker run -v $(pwd):/map2loop docs bash map2loop/docs/build_docs.sh
+      - name: upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          path: docs/build/html
   release-please:
     runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master'
     steps:
       - uses: GoogleCloudPlatform/release-please-action@v3
         id: release
@@ -69,41 +80,41 @@ jobs:
           miniforge-variant: Mambaforge
           miniforge-version: latest
           use-mamba: true
-    
+
       - uses: actions/checkout@v2
       - name: update submodules
         run: |
-            git submodule update --init --recursive
+          git submodule update --init --recursive
       - name: Add msbuild to PATH
         if: matrix.os == 'windows-latest'
-        uses: microsoft/[email protected]  
+        uses: microsoft/[email protected]
       - name: Conda build'
         env:
           ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_TOKEN  }}
         shell: bash -l {0}
         run: |
-           conda install conda-build
-           conda install -c loop3d --file dependencies.txt -y
-           conda build -c loop3d --no-test --python ${{ matrix.python-version }} --output-folder conda conda
-           conda install anaconda-client -y
+          conda install conda-build
+          conda install -c loop3d --file dependencies.txt -y
+          conda build -c loop3d --no-test --python ${{ matrix.python-version }} --output-folder conda conda
+          conda install anaconda-client -y
       - name: upload windows
         env:
           ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_TOKEN  }}
         if: matrix.os == 'windows-latest'
         shell: bash -l {0}
         run: |
-           anaconda upload --label main conda/win-64/*.tar.bz2 
+          anaconda upload --label main conda/win-64/*.tar.bz2
       - name: upload linux
         env:
           ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_TOKEN  }}
         if: matrix.os == 'ubuntu-latest'
         shell: bash -l {0}
         run: |
-           anaconda upload --label main conda/linux-64/*.tar.bz2 
+          anaconda upload --label main conda/linux-64/*.tar.bz2
       - name: upload macosx
         env:
           ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_TOKEN  }}
         if: matrix.os == 'macos-latest'
         shell: bash -l {0}
         run: |
-            anaconda upload --label main conda/osx-64/*.tar.bz2
+          anaconda upload --label main conda/osx-64/*.tar.bz2

.gitignore

@@ -212,4 +212,8 @@ docs/source/_autosummary/*
 # End of https://www.toptal.com/developers/gitignore/api/python,visualstudiocode,c++,cmake
 #ignore automatically generated doc files
 docs/source/_autosummary 
-
+docs/source/_auto_examples/*
+docs/source/_auto_examples
+examples/*_tmp
+*.loop3d
+m2l_data_tmp/*

README.md

@@ -1,9 +1,8 @@
 # Map2Loop 3.0
 
-Generate 3D geological model inputs from geographical maps — a high-level implementation and extension of the original map2loop code developed by Prof. Mark Jessell at UWA. To see an example interactive model built with map2loop and LoopStructural, follow this link:   
-
-<a href="http://tectonique.net/models/brockman_syncline.html">3D Model from the Hamersley region, Western Australia</a>
+Generate 3D geological model inputs from geological maps — a high-level implementation and extension of the original map2loop code developed by Prof. Mark Jessell at UWA. To see an example interactive model built with map2loop and LoopStructural, follow this link:
 
+<a href="http://tectonique.net/models/brockman_syncline.html">3D Model from the Hamersley region, Western Australia</a>
 
 ## Install
 
@@ -16,26 +15,27 @@ To just use map2loop, issue the following
 ```bash
 conda install -c conda-forge -c loop3d map2loop -y
 ```
+
 ### Documentation
 
-If you can call it that, is available  <a href="http://13.211.217.129/m2ldocs/">here</a>
+If you can call it that, is available <a href="http://13.211.217.129/m2ldocs/">here</a>
 
 ### Development
 
 If you want to tinker yourself/contribute, clone the source code with
 
 ```bash
-git clone https://github.com/Loop3D/map2loop-3.git
+git clone https://github.com/Loop3D/map2loop.git
 ```
 
 Or get the source + example notebooks with
 
 ```bash
-git clone https://github.com/Loop3D/map2loop-3.git
+git clone https://github.com/Loop3D/map2loop.git
 git clone --single-branch --branch yohan https://github.com/Loop3D/map2loop-3-notebooks
 ```
 
-Navigate into map2loop-3, and issue the following to install map2loop and its dependencies. _Note_: The 'develop' flag makes your source changes take effect on saving, so you only need to run this once
+Navigate into map2loop, and issue the following to install map2loop and its dependencies. _Note_: The 'develop' flag makes your source changes take effect on saving, so you only need to run this once
 
 ```bash
 conda install -c loop3d --file dependencies.txt
@@ -46,7 +46,7 @@ pip install .
 
 Fair warning, we recommend conda to almost everyone. With great software development power comes great environment setup inconvenience. You'll need to download and install the [docker containerisation software](https://docs.docker.com/get-docker/), and the docker and docker-compose CLI.
 
-### Development 
+### Development
 
 1. Clone this repo and navigate inside as per above
 2. Run the following and click on the Jupyter server forwarded link to access and edit the notebooks
@@ -65,9 +65,9 @@ Fair warning, we recommend conda to almost everyone. With great software develop
 
    ```bash
    docker exec -it <container_NAMEorID> bash
-   # Probably -> docker exec -it  map2loop-3_dev_1 bash
+   # Probably -> docker exec -it  map2loop_dev_1 bash
    ```
- 
+
 ## Usage
 
 Our notebooks cover use cases in more detail, but here is an example of processing Loop's South Australia remote geospatial data in just 20 lines of Python.
@@ -78,7 +78,7 @@ First, lets import map2loop and define a bounding box. You can use GIS software
 from map2loop.project import Project
 from map2loop.m2l_enums import VerboseLevel
 
-# Note that this region is defined in the EPSG 28354 projection and 
+# Note that this region is defined in the EPSG 28354 projection and
 # x and y represent easting and northing respectively
 bbox_3d = {
     'minx': 250805.1529856466,

conda/meta.yaml

@@ -7,7 +7,7 @@ package:
   version: "3.0.6"
 
 source:
-  git_url: https://github.com/Loop3D/map2loop-3
+  git_url: https://github.com/Loop3D/map2loop
 
 build:
   number: 0
@@ -47,7 +47,7 @@ test:
     - owslib
 
 about:
-  home: "https://github.com/Loop3D/map2loop-3"
+  home: "https://github.com/Loop3D/map2loop"
   license: MIT
   license_family: MIT
   license_file: ../LICENSE

docs/Dockerfile

@@ -0,0 +1,34 @@
+FROM continuumio/miniconda3
+LABEL maintainer="[email protected]"
+#This docker image has been adapted from the lavavu dockerfile
+# install things
+
+
+RUN apt-get update -qq && \
+    DEBIAN_FRONTEND=noninteractive apt-get install -yq --no-install-recommends \
+    gcc \
+    g++ \
+    libc-dev \
+    make\
+    libgl1\
+    libtinfo5\
+    libtiff5\
+    libgl1-mesa-glx
+COPY . /map2loop
+WORKDIR /map2loop
+COPY dependencies.txt dependencies.txt
+RUN conda install -c conda-forge -c loop3d --file dependencies.txt
+RUN conda install -c conda-forge -c loop3d LoopStructural
+RUN pip install -r docs/requirements.txt
+RUN pip install .
+RUN pip install git+https://github.com/Loop3D/LoopStructural.git
+RUN pip install lavavu-osmesa==1.8.45 
+ENV LD_LIBRARY_PATH=/opt/conda/lib/python3.10/site-packages/lavavu_osmesa.libs
+RUN conda install -c conda-forge pydata-sphinx-theme 
+RUN pip install sphinxcontrib-bibtex
+ENV TINI_VERSION v0.19.0
+ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini /tini
+RUN chmod +x /tini
+# ENTRYPOINT ["/tini", "--"]
+
+WORKDIR /

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     = source
+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/build_docs.sh

@@ -0,0 +1,2 @@
+pip install ./map2loop
+make -C map2loop/docs html

docs/docker-compose.yml

@@ -0,0 +1,12 @@
+version: "3"
+
+services:
+  map2loop:
+    build:
+      dockerfile: docs/Dockerfile
+      context: ../
+    volumes:
+      - ../:/map2loop
+      - ../../LoopStructural:/LoopStructural
+    tty: true
+    command: sh map2loop/docs/build_docs.sh

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=source
+set BUILDDIR=build
+
+%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
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+sphinx-gallery
+pydata-sphinx-theme
+myst-parser

docs/source/API.rst

@@ -0,0 +1,10 @@
+API
+---
+
+.. autosummary::
+   :caption: API
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   map2loop

docs/source/_templates/custom-class-template.rst

@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:                                   
+   :show-inheritance:                           
+   :inherited-members:                          
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}