setup sphinx doc

.github/workflows/doc.yml

@@ -0,0 +1,55 @@
+name: "Sphinx: Render docs"
+
+on: 
+  push:
+    branches:
+      - 'master'
+
+env:
+  GIT_USER_NAME: BattINFO Developers
+  GIT_USER_EMAIL: "[email protected]"
+
+jobs:
+
+  updatepages:
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v4 #Uses python install action from here: https://github.com/marketplace?type=actions
+      with:
+        python-version: '3.10'  # Replace with the desired Python version
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install Markdown==3.4.3 rdflib==6.3.2  # Add any other dependencies if needed
+        
+    - name: Render documentation from ttl
+      run: python sphinx/ttl_to_rst.py
+
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "sphinx/"
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentationHTML
+        path: sphinx/_build/html/
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/master'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: sphinx/_build/html
+

sphinx/.gitignore

@@ -0,0 +1 @@
+_build

sphinx/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    ?= -v
+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)

sphinx/README.org

@@ -0,0 +1,47 @@
+#+TITLE: Documentation generation for BattInfo
+* Requirements
+** sphinx
+   installation instruction described [[https://www.sphinx-doc.org/en/master/usage/installation.html][here]]
+   #+begin_src
+     pip install sphinx
+   #+end_src
+** install sphinx pydata theme
+   https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html
+   #+begin_src
+     pip install pydata-sphinx-theme
+   #+end_src
+** globabsubs extension
+   #+begin_src
+     pip install sphinxcontrib-globalsubs
+   #+end_src
+** autosectionlabel
+   - part of default distribution
+   - We use ~autosectionlabel_prefix_document = True~ which means that the internal link must be prefixed by the file
+     name and a semi-column, see [[https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html][here]].
+
+* Workflow for editing
+
+  In the ~Documentation~ directory, run from terminal
+  #+BEGIN_SRC sh
+  make html
+  #+END_SRC
+
+  The command generates all the files for a static website and writes them in ~Documentation/_build/html~
+
+  All the files in this directory must then be copied to the ~BattInfo-doc~ [[https://github.com/BattMoTeam/BattMo-doc][repo]]. From there, make a *force* push. We do
+  not keep track of the history of the ouput files (html), but we of course keep track of the documentation source, directly in the
+  main repo ~BattInfo~.
+
+  The deployment of the webpage can be followed from the [[https://github.com/BattMoTeam/BattMo-doc/actions][github pages section]]
+
+  The result can be view at
+
+  https://battmoteam.github.io/Battinfo-doc/
+
+* Interesting Manuals
+** sphinx manual
+   https://www.sphinx-doc.org/en/master/contents.html
+** reStucturedText (rst) format
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+* Configuration file
+  - ~conf.py~ see https://www.sphinx-doc.org/en/master/usage/configuration.html

sphinx/about.rst

@@ -0,0 +1,34 @@
+About Electrochemistry Domain Ontology
+======================================
+
+Contributors
+------------
+
+-  Simon Clark, SINTEF, Norway
+-  Eibar Flores, SINTEF, Norway
+-  Francesca Lønstad Bleken, SINTEF, Norway
+-  Jesper Friis, SINTEF, Norway
+-  Casper Welzel Andersen, SINTEF, Norway
+-  Martin Uhrin, EPFL, Switzerland
+-  Simon Stier, Fraunhofer, Germany
+-  Marek Marcinek, Warsaw University of Technology, Poland
+-  Anna Szczesna, Warsaw University of Technology, Poland
+-  Miran Gaberscek, National Institute of Chemistry, Slovenia
+-  Deyana Stoytcheva, ICMAB, Spain
+-  Rosa Palacin, ICMAB, Spain
+-  Ingeborg-Helene Svenum, SINTEF, Norway
+-  Inga Gudem Ringdalen, SINTEF, Norway
+-  Emanuele Farhi, SOLEIL synchrotron, France
+
+Projects
+--------
+
+-  `BIG-MAP <http://www.big-map.eu/>`__; Grant Agreement No: 957189
+
+License
+-------
+
+The Battery Interface Domain Ontology is released under the `Creative
+Commons Attribution 4.0
+International <https://creativecommons.org/licenses/by/4.0/legalcode>`__
+license (CC BY 4.0).