Merge pull request #122 from reflectivity/self-build-docs

adding self-build of docs (publishes to gh-pages branch)

.github/workflows/docs_build.yml

@@ -0,0 +1,37 @@
+name: Sphinx docs to gh-pages
+
+on:
+  push:
+    tags:
+      - "v*"
+
+  workflow_dispatch:        # Un comment line if you also want to trigger action manually
+
+jobs:
+  sphinx_docs_to_gh-pages:
+    runs-on: ubuntu-latest
+    name: Sphinx docs to gh-pages
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Make conda environment
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: "3.10"    # Python version to build the html sphinx documentation
+          environment-file: docs_env.yaml    # Path to the documentation conda environment
+          auto-update-conda: false
+          auto-activate-base: false
+          show-channel-urls: true
+      - name: Installing the library
+        shell: bash -l {0}
+        run: |
+          python setup.py install
+      - name: Running the Sphinx to gh-pages Action
+        uses: uibcdf/[email protected]
+        with:
+          branch: main
+          dir_docs: docs
+          sphinx-apidoc-opts: '--separate -o . ../'
+          sphinx-apidoc-exclude: '../*setup* ../*.ipynb'
+          sphinx-opts: ''

README.rst

@@ -35,4 +35,4 @@ Features
 .. _`Documents`: https://orsopy.readthedocs.io/en/latest/documents.html
 .. _`contribute`: https://orsopy.readthedocs.io/en/latest/contributing.html
 .. _`ORSO Slack`: https://join.slack.com/t/orso-co/shared_invite/zt-z7p3v89g-~JgCbzcxurQP6ufqdfTCfw
-.. _`Reading and writing of ORSO specification reduced reflectivity files`: https://orsopy.rtfd.io/en/latest/modules.html#fileio
+.. _`Reading and writing of ORSO specification reduced reflectivity files`: modules.html#fileio

docs/conf.py

@@ -47,7 +47,7 @@
 
 # General information about the project.
 project = 'orsopy'
-copyright = "2021, ORSO"
+copyright = "2024, ORSO"
 author = "ORSO"
 
 # The version info for the project you're documenting, acts as replacement

docs_env.yaml

@@ -0,0 +1,24 @@
+name: docs
+
+channels:
+
+  - conda-forge
+  - defaults
+
+dependencies:
+
+  # Write here all dependencies to compile the sphinx documentation.
+  # This list is just an example
+  - python=3.10
+  - numpy
+  - pint
+  - pytest
+  - h5py
+  - typing_extensions
+  - sphinx
+  - sphinx_rtd_theme
+  - sphinxcontrib-bibtex
+  - sphinx-autodoc-typehints
+  - nbsphinx
+  - recommonmark
+  - sphinx-markdown-tables