Merge pull request #99 from NASA-IMPACT/feature-docs

Feature docs

.github/gh-pages.yml

@@ -0,0 +1,54 @@
+# config details can be found on https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-static-site-generators-with-python
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - feature-docs
+      - main
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.8'
+
+      - name: Upgrade pip
+        run: |
+          # install pip=>20.1 to use "pip cache dir"
+          python3 -m pip install --upgrade pip
+
+      - name: Get pip cache dir
+        id: pip-cache
+        run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.pip-cache.outputs.dir }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements/local.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: python3 -m pip install -r ./requirements/local.txt
+
+      - name: Build Sphinx docs
+        run: sphinx-build -b html ./docs ./docs/_build
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/feature-docs' || github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build

docs/conf.py

@@ -14,7 +14,8 @@
 import sys
 import django
 
-if os.getenv("READTHEDOCS", default=False) == "True":
+# if os.getenv("READTHEDOCS", default=True) == "True":
+if True:
     sys.path.insert(0, os.path.abspath(".."))
     os.environ["DJANGO_READ_DOT_ENV_FILE"] = "True"
     os.environ["USE_DOCKER"] = "no"
@@ -28,8 +29,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "SDE Indexing Helper"
-copyright = """2023, Ashish Acharya"""
-author = "Ashish Acharya"
+copyright = """2023, NASA IMPACT"""
+author = "NASA IMPACT"
 
 
 # -- General configuration ---------------------------------------------------
@@ -40,6 +41,9 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
+    "sphinx_rtd_theme",
+    "sphinx_toolbox.code",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -55,7 +59,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/documentation/sinequa_api.rst

@@ -0,0 +1,12 @@
+ .. _sinequa_api:
+
+Using the Sinequa API
+=====================
+Overview
+---------------------
+The Indexing Helper currently uses the API to start indexing arbitrary collections, and it is capable of executing queries as well.
+The api class can be found in config_generation/api.py and by default is linked to the the ren server.
+
+The Sinequa documentation has several useful links.
+`Generating an Access Token <https://doc.sinequa.com/en.sinequa-es.v11/Content/en.sinequa-es.how-to.access-tokens.html>`_
+

docs/howto.rst

@@ -24,8 +24,6 @@ The sphinx extension `apidoc <https://www.sphinx-doc.org/en/master/man/sphinx-ap
 
 Numpy or Google style docstrings will be picked up from project files and available for documentation. See the `Napoleon <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/>`_ extension for details.
 
-For an in-use example, see the `page source <_sources/users.rst.txt>`_ for :ref:`users`.
-
 To compile all docstrings automatically into documentation source files, use the command:
     ::
     

docs/index.rst

@@ -8,16 +8,21 @@ Welcome to SDE Indexing Helper's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Working with Sinequa:
 
+   documentation/sinequa_api
    howto
-   users
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Using the Indexing Helper:
+
+   documentation/indexing_guidelines
 
 
 
-Indices and tables
+Quick Links
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+* :ref:`sinequa_api`
+* :ref:`indexing_guidelines`

requirements/local.txt

@@ -18,6 +18,8 @@ types-xmltodict
 # ------------------------------------------------------------------------------
 sphinx==7.2.6  # https://github.com/sphinx-doc/sphinx
 sphinx-autobuild==2021.3.14 # https://github.com/GaretJax/sphinx-autobuild
+sphinx-rtd-theme==1.2.0
+sphinx_toolbox==3.4.0
 
 # Code quality
 # ------------------------------------------------------------------------------