diff --git a/.github/gh-pages.yml b/.github/gh-pages.yml new file mode 100644 index 00000000..b2061603 --- /dev/null +++ b/.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 diff --git a/docs/conf.py b/docs/conf.py index 455f0310..93a07713 100644 --- a/docs/conf.py +++ b/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, diff --git a/docs/documentation/indexing_guidelines.rst b/docs/documentation/indexing_guidelines.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/documentation/sinequa_api.rst b/docs/documentation/sinequa_api.rst new file mode 100644 index 00000000..3f1569b2 --- /dev/null +++ b/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 `_ + diff --git a/docs/howto.rst b/docs/howto.rst index 25466955..fd6a13a7 100644 --- a/docs/howto.rst +++ b/docs/howto.rst @@ -24,8 +24,6 @@ The sphinx extension `apidoc `_ 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: :: diff --git a/docs/index.rst b/docs/index.rst index e1c67e00..8faba818 100644 --- a/docs/index.rst +++ b/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` diff --git a/docs/users.rst b/docs/users.rst deleted file mode 100644 index 5f600703..00000000 --- a/docs/users.rst +++ /dev/null @@ -1,15 +0,0 @@ - .. _users: - -Users -====================================================================== - -Starting a new project, it’s highly recommended to set up a custom user model, -even if the default User model is sufficient for you. - -This model behaves identically to the default user model, -but you’ll be able to customize it in the future if the need arises. - -.. automodule:: sde_indexing_helper.users.models - :members: - :noindex: - diff --git a/requirements/local.txt b/requirements/local.txt index ca2cf66e..11018a7c 100644 --- a/requirements/local.txt +++ b/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 # ------------------------------------------------------------------------------