Integrate with new AequilibraE docs (#380)

* Create custom.css * Create navbar-nav.html * config layout * conf * toggle button * nav bars * update pages * new menus * Update documentation.yml * update headers * add grid * update docs * update docs and build pdf * Update documentation.yml * fixes PDF creation * Update documentation.yml * modifies page structure * Update documentation.yml * update docs * updates links * updates links and files * update website links
AequilibraE · Nov 21, 2024 · e02afe6 · e02afe6
1 parent b75e62f
commit e02afe6
Show file tree

Hide file tree

Showing 26 changed files with 424 additions and 401 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -14,20 +14,25 @@ jobs:
       max-parallel: 4
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.9
+    - name: Set up Python 3.10
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        python-version: '3.10'
+
     - name: Install dependencies
       run: |
+        sudo apt-get update
+        sudo apt-get install -y --fix-missing latexmk texlive-latex-extra
         python -m pip install -U pip
         pip install -r docs/requirements-docs.txt
 
     - name: Build documentation
       run: |
+        cp qaequilibrae/large_icon.png docs/source/_static/large_icon.png
+        sphinx-build -M latexpdf docs/source docs/source/_static
         cd docs
         make html
-
+  
     - name: Upload documentation to dev
       uses: jakejarvis/s3-sync-action@7ed8b112447abb09f1da74f3466e4194fc7a6311
       with:
@@ -38,7 +43,7 @@ jobs:
         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
         AWS_REGION: 'us-east-1'   # optional: defaults to us-east-1
         SOURCE_DIR: 'docs/build/html/'      # optional: defaults to entire repository
-        DEST_DIR: 'qgis/dev'      # optional: defaults to entire repository
+        DEST_DIR: 'dev/${{ github.event.number}}/qgis'      # optional: defaults to entire repository
 
     - name: Upload documentation to the latest folder
       if: ${{ (github.event_name == 'release')}}
@@ -51,7 +56,7 @@ jobs:
         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
         AWS_REGION: 'us-east-1'   # optional: defaults to us-east-1
         SOURCE_DIR: 'docs/build/html/'      # optional: defaults to entire repository
-        DEST_DIR: 'qgis/latest/'      # optional: defaults to entire repository
+        DEST_DIR: 'latest/qgis'      # optional: defaults to entire repository
 
     - name: Upload documentation to the version folder
       if: ${{ (github.event_name == 'release')}}
@@ -64,4 +69,4 @@ jobs:
         AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
         AWS_REGION: 'us-east-1'   # optional: defaults to us-east-1
         SOURCE_DIR: 'docs/build/html/'      # optional: defaults to entire repository
-        DEST_DIR: 'qgis/github.event.release.tag_name'      # optional: defaults to entire repository
+        DEST_DIR: 'docs/qgis/github.event.release.tag_name'      # optional: defaults to entire repository
diff --git a/.gitignore b/.gitignore
@@ -58,6 +58,7 @@ aequilibrae/paths/build/*
 qaequilibrae/packages
 .coverage
 docs/build
+docs/source/_static
 
 __pycache__/
 

diff --git a/README.txt b/README.txt
@@ -1,11 +1,8 @@
-This Add-on for QGIS is developed with the intention to provide transportation planning tools in a GIS environment
-This add-on is FREE and open source.
-It can also be used on a Python shell. For initial instruction on how to do it, access https://github.com/AequilibraE/examples_api
+QAequilibraE is the GUI for AequilibraE, a transportation modeling package designed to be an open-source alternative to
+traditional commercial packages. 
 
-For more details: www.aequilibrae.com/qgis
+It is a comprehensive set of tools for modeling and visualization, including incredibly fast equilibrium traffic 
+assignment, synthetic gravity models, network editing, and GTFS importer. 
 
-
-
-Youtube playlist: https://www.youtube.com/playlist?list=PLdiSu_6yrzc5OtDnPXZ1PEAw2bEeEUJoY
-
-Plugin Page: www.aequilibrae.com
+If you want to go further, explore [AequilibraE](https://github.com/AequilibraE/aequilibrae), the open-source Python 
+package for transportation modeling.    
diff --git a/docs/source/_latex/index.rst b/docs/source/_latex/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+QGIS
+====
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   ../getting_started
+   ../menus_in_detail
+   ../processing_provider
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -0,0 +1,11 @@
+.bd-page-width {
+    max-width: 80%;
+}
+
+.bd-main .bd-content .bd-article-container {
+    max-width: 80%;
+}
+
+.bd-links__title[role="heading"][aria-level="1"] {
+    display: none;
+}
diff --git a/docs/source/_templates/navigation_header.html b/docs/source/_templates/navigation_header.html
@@ -0,0 +1,52 @@
+<nav>
+  <ul class="bd-navbar-elements navbar-nav">
+    <li class="nav-item">
+      <a class="nav-link" href="https://www.aequilibrae.com/latest/python.html">Python</a>
+    </li>
+    <li class="nav-item dropdown">
+      <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="true"
+        aria-controls="pst-nav-more-links" id="qgis-button">
+        QGIS
+      </button>
+      <ul id="pst-nav-more-links" class="dropdown-menu" data-bs-popper="static">
+        <li class=" ">
+          <a class="nav-link dropdown-item nav-internal" 
+            href="https://www.aequilibrae.com/latest/qgis.html">
+            Main menu
+        </a>
+        </li>
+        <li class=" ">
+          <a class="nav-link dropdown-item nav-internal"
+            href="https://www.aequilibrae.com/latest/qgis/getting_started.html">
+            Getting Started
+          </a>
+        </li>
+        <li class=" ">
+          <a class="nav-link dropdown-item nav-internal"
+            href="https://www.aequilibrae.com/latest/qgis/menus_in_detail.html">
+            Menus in detail
+          </a>
+        </li>
+        <li class=" ">
+          <a class="nav-link dropdown-item nav-internal"
+            href="https://www.aequilibrae.com/latest/qgis/processing_provider.html">
+            Processing provider
+          </a>
+        </li>
+      </ul>
+    </li>
+  </ul>
+</nav>
+
+<script>
+  document.adlatestentListener("DOMContentLoaded", function () {
+    const isQGISPage = window.location.pathname.endsWith("qgis.html");
+    const qgisButton = document.getElementById("qgis-button");
+
+    if (!isQGISPage) {
+      qgisButton.innerHTML = "<b>QGIS</b>";
+    }
+  });
+</script>
+
+<!-- TODO: Fix navigation links-->
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -14,17 +14,16 @@
 
 import os
 import sys
+from datetime import datetime
 
 sys.path.insert(0, os.path.abspath("../.."))
-#
 
 # -- Project information -----------------------------------------------------
 
 project = "AequilibraE for QGIS"
-copyright = "2018, AequilibraE developers"
+copyright = f"{str(datetime.now().date())}, AequilibraE developers"
 author = "Pedro Camargo"
 
-
 # The short X.Y.Z version
 
 a = open("../../qaequilibrae/metadata.txt", "r")
@@ -33,150 +32,102 @@
         version = line.rstrip()[8:]
 
 # The full version, including alpha/beta/rc tags
-release = "30/07/2018"
-
+release = version
 
 # -- General configuration ---------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ["sphinx_panels", "sphinx_subfigure"]
+# Sphinx extension module names
+extensions = ["sphinx_panels", "sphinx_subfigure", "sphinx_design"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
 source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = "index"
+master_doc = "qgis"
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
+# The language for content autogenerated by Sphinx.
 language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path .
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
 html_theme = "pydata_sphinx_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
+# further. For a list of options available for each theme, see the
 # documentation.
-#
 html_theme_options = {
-    "show_nav_level": 0,
-    "github_url": "https://github.com/AequilibraE/qaequilibrae",
+    "navbar_center": ["navigation_header"],
+    "navbar_start": ["navbar-logo"],
     "navbar_end": ["theme-switcher", "navbar-icon-links"],
-    "navbar_persistent": ["search-button"],
+    "navbar_persistent":["search-button"],
+    "navbar_align": "left",
+    "github_url": "https://github.com/AequilibraE/qaequilibrae",
+    "logo": {
+        "text": "AequilibraE",
+        "image_light": "_static/large_icon.png",
+        "image_dark": "_static/large_icon.png",
+        "link": "https://www.aequilibrae.com/latest/home.html",
+    },
 }
 
-# The name for this set of Sphinx documents.  If None, it defaults to
+# The name for this set of Sphinx documents. If None, it defaults to
 html_title = f"AequilibraE for QGIS"
 
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don't match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
-# 'searchbox.html']``.
-#
-# html_sidebars = {}
+html_static_path = ["_static"]
 
+html_css_files = ["custom.css"]
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "AequilibraEdoc"
 
-
 # -- Options for LaTeX output ------------------------------------------------
+latex_documents = [("_latex/index", "qaequilibrae.tex", "AequilibraE for QGIS", author, "manual")]
 
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [(master_doc, "AequilibraE.tex", "AequilibraE Documentation", "Pedro Camargo", "manual")]
-
+latex_appendices = [
+    "development/softwaredevelopment",
+    "development/i18n",
+    "development/support",
+    "development/citation",
+]
 
 # -- Options for manual page output ------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "aequilibrae", "AequilibraE Documentation", [author], 1)]
-
+man_pages = [(master_doc, "aequilibrae", "AequilibraE for QGIS", [author], 1)]
 
 # -- Options for Texinfo output ----------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
+# (source start file, target name, title, author, dir menu entry, description, category)
 texinfo_documents = [
     (
         master_doc,
         "AequilibraE",
-        "AequilibraE Documentation",
+        "AequilibraE for QGIS",
         author,
         "AequilibraE",
-        "One line description of project.",
+        "A QGIS plugin for transportation modeling",
         "Miscellaneous",
     )
 ]
 
-
-# -- Extension configuration -------------------------------------------------
-
 # -- Options for intersphinx extension ---------------------------------------
-
-# Example configuration for intersphinx: refer to the Python standard library.
-# intersphinx_mapping = {"https://docs.python.org/": None}
-#
-# autodoc_mock_imports = [
-#     "numpy",
-#     "scipy",
-#     "aequilibrae.paths.AoN",
-#     "aequilibrae.distribution",
-# ]
 add_module_names = False
diff --git a/docs/source/development/citation.rst b/docs/source/development/citation.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+.. _citation:
+
+Cite us!
+========
+
+If you're using QAequilibraE in a scientific publication, we would appreciate citations 
+to the following paper:
+
+    Camargo, P. (2015) AequilibraE: a free QGIS add-on for transportation modeling. Foss4g North America
+
diff --git a/docs/source/development/contributors.rst b/docs/source/development/contributors.rst