From 6b8d3001866b6529c9f4a60993da8542e8bf0aa1 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 10:32:30 -0500 Subject: [PATCH 01/10] add workflow to update gh-pages --- .github/gh-pages.yml | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 .github/gh-pages.yml diff --git a/.github/gh-pages.yml b/.github/gh-pages.yml new file mode 100644 index 00000000..464ed654 --- /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 + - master + 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/master' }} + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build From 7566d538c0e8edda108c7bf22f543dce34e9b2e1 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:12:38 -0500 Subject: [PATCH 02/10] remove users.rst --- docs/users.rst | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 docs/users.rst 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: - From 2e837476b062cf90d07f5b824a2f772c44c9c30d Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:12:58 -0500 Subject: [PATCH 03/10] use rtd theme and hardcode some config options --- docs/conf.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) 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, From 798a5f1bf3dfa8e401be31b4d054726db833d790 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:13:06 -0500 Subject: [PATCH 04/10] remove users --- docs/howto.rst | 2 -- 1 file changed, 2 deletions(-) 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: :: From e87fa37ce0d925a3aaca87256faf643c70b23888 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:18:24 -0500 Subject: [PATCH 05/10] add indexing guidelines --- docs/index.rst | 18 ++++++++++++------ docs/indexing_guidelines.rst | 12 ++++++++++++ 2 files changed, 24 insertions(+), 6 deletions(-) create mode 100644 docs/indexing_guidelines.rst diff --git a/docs/index.rst b/docs/index.rst index e1c67e00..673ecf92 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,16 +8,22 @@ Welcome to SDE Indexing Helper's documentation! .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Working with Sinequa: + documentation/sinequa_api + documentation/example 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/indexing_guidelines.rst b/docs/indexing_guidelines.rst new file mode 100644 index 00000000..e91ba187 --- /dev/null +++ b/docs/indexing_guidelines.rst @@ -0,0 +1,12 @@ + .. _indexing_guidelines: + +Deciding what to Index +===================== +General Guidelines +--------------------- +- Indexed documents must be discoverable, either by text searching or by filtering. (Documents require filterable metadata or text to search on +- If it doesn’t have at least one of these things, then it does not bring value to index it. +- Indexed documents must be relevant to the scope of the SDE. +- Content for indexing is identified by subject matter experts within the SDE team or by scientists at SMD. + +todo: add more content... \ No newline at end of file From 339a80c9707099310b5206fa2c0ada981dfe2a83 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:19:04 -0500 Subject: [PATCH 06/10] move indexing guidelines location --- docs/documentation/indexing_guidelines.rst | 0 docs/indexing_guidelines.rst | 12 ------------ 2 files changed, 12 deletions(-) create mode 100644 docs/documentation/indexing_guidelines.rst delete mode 100644 docs/indexing_guidelines.rst 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/indexing_guidelines.rst b/docs/indexing_guidelines.rst deleted file mode 100644 index e91ba187..00000000 --- a/docs/indexing_guidelines.rst +++ /dev/null @@ -1,12 +0,0 @@ - .. _indexing_guidelines: - -Deciding what to Index -===================== -General Guidelines ---------------------- -- Indexed documents must be discoverable, either by text searching or by filtering. (Documents require filterable metadata or text to search on -- If it doesn’t have at least one of these things, then it does not bring value to index it. -- Indexed documents must be relevant to the scope of the SDE. -- Content for indexing is identified by subject matter experts within the SDE team or by scientists at SMD. - -todo: add more content... \ No newline at end of file From ea6332c816bce9d83d44cf769301d40125192907 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:19:16 -0500 Subject: [PATCH 07/10] add details on sinequa api --- docs/documentation/sinequa_api.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/documentation/sinequa_api.rst 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 `_ + From 0aa3aff97f1660e5909a83470013f4a0757ac27e Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:19:36 -0500 Subject: [PATCH 08/10] add rtd and toolbox to requirements --- requirements/local.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/requirements/local.txt b/requirements/local.txt index 0b1e4491..9968acb6 100644 --- a/requirements/local.txt +++ b/requirements/local.txt @@ -16,6 +16,8 @@ pytest-sugar==0.9.7 # https://github.com/Frozenball/pytest-sugar # ------------------------------------------------------------------------------ sphinx==7.0.1 # 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 # ------------------------------------------------------------------------------ From 7b950ad44685d101c2ecadffe85c4694b6341b72 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 12:20:08 -0500 Subject: [PATCH 09/10] remove example from index --- docs/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 673ecf92..8faba818 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,7 +11,6 @@ Welcome to SDE Indexing Helper's documentation! :caption: Working with Sinequa: documentation/sinequa_api - documentation/example howto .. toctree:: From cf516354fce1e45c2c770a3e8cb75c60c7194ac6 Mon Sep 17 00:00:00 2001 From: Carson Davis Date: Fri, 19 May 2023 13:41:21 -0500 Subject: [PATCH 10/10] correct main to master --- .github/gh-pages.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/gh-pages.yml b/.github/gh-pages.yml index 464ed654..b2061603 100644 --- a/.github/gh-pages.yml +++ b/.github/gh-pages.yml @@ -5,7 +5,7 @@ on: push: branches: - feature-docs - - master + - main pull_request: jobs: @@ -48,7 +48,7 @@ jobs: - name: Deploy uses: peaceiris/actions-gh-pages@v3 - if: ${{ github.ref == 'refs/heads/feature-docs' || github.ref == 'refs/heads/master' }} + if: ${{ github.ref == 'refs/heads/feature-docs' || github.ref == 'refs/heads/main' }} with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/_build