Merge pull request #21 from kitware-resonant/build

Refactor build system

Author: brianhelba

.github/workflows/doc.yml

@@ -0,0 +1,48 @@
+name: pages
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+concurrency:
+  # Only run the latest workflow per-branch
+  group: "${{ github.workflow }}-${{ github.ref_name }}"
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Install Poetry
+        run: |
+          pip install --upgrade pip
+          pip install poetry
+      - name: Install project
+        run: |
+          poetry install
+      - name: Build docs
+        run: |
+          poetry run task build
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "build/html"
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pages.yml

@@ -1,2 +1,3 @@
-resonant_docs/build
+/build
+
 .DS_Store

.gitignore

@@ -1,23 +1,8 @@
-# resonant
+# Resonant
+Resonant marketing website.
 
-Resonant documentation materials.
-
-## Build instructions
-
-You can use `poetry` to build and view the documentation locally. There are two
-ways to do it.
-
-
-### Static build
-
-1. Run `poetry install` to build the dependencies.
-2. Run `poetry run task build` to build the documentation.
-3. Run `poetry run task serve` to serve the docs on port 8000 (or `poetry run
-   task serve 8001` to use a different port of your choice).
-
-### Watch mode build.
-
-1. Run `poetry install` to build the dependencies.
-2. Run `poetry run task watch` to build and serve the docs on port 8000 (or
-   `poetry run task watch PORT=8001` to use a different port of your choice).
+## Development instructions
+1. [Install Poetry](https://python-poetry.org/docs/#installation)
+2. Run `poetry install` to build the dependencies.
+2. Run `poetry run task watch` to build and serve the docs.
    Changes to the documentation source code will cause an automatic rebuild.

CNAME

@@ -1,25 +1,26 @@
 [tool.poetry]
 name = "resonant_docs"
 version = "0.1.0"
-description = "Documentation for Resonant"
+description = "Resonant marketing website"
 authors = ["Kitware D&A Team <[email protected]>"]
 
 [tool.poetry.dependencies]
-python = "^3.8"
+python = "^3.12"
 
-[tool.poetry.dev-dependencies]
-Sphinx = "^4.5.0"
-sphinx-copybutton = "^0.5.0"
-sphinx-notfound-page = "^0.8"
-sphinx-panels = "^0.6.0"
-furo = "^2022.4.7"
-taskipy = "^1.10.2"
-sphinx-autobuild = "^2021.3.14"
+[tool.poetry.group.docs.dependencies]
+sphinx = "^7.4.5"
+sphinx-copybutton = "^0.5.2"
+sphinx-design = "^0.6.0"
+furo = "^2024.5.6"
+
+[tool.poetry.group.dev.dependencies]
+taskipy = "^1.13.0"
+sphinx-autobuild = "^2024.4.16"
 
 [tool.taskipy.tasks]
-build = { cmd = "make html -C doc", help = "Build the HTML documentation" }
-serve = { cmd = "python -m http.server --bind 127.0.0.1 -d doc/build/html", help = "Serve the built docs (supply an optional port number, 8000 by default)" }
-watch = { cmd = "make livehtml -C doc", help = "Build the HTML documentation in watch mode" }
+pre_build = "rm -rf ./build"
+build = "sphinx-build -M html resonant_docs build"
+watch = "sphinx-autobuild --port 0 resonant_docs build"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

README.md

@@ -0,0 +1,55 @@
+# -- Project information -----------------------------------------------------
+project = "Resonant"
+copyright = "2024, Kitware, Inc."
+author = "Kitware, Inc."
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    "sphinx_copybutton",
+    "sphinx_design",
+]
+
+# 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", "**.ipynb_checkpoints"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "friendly"
+
+smartquotes = True
+
+# -- 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 = "furo"
+
+html_title = project
+html_logo = "_static/img/resonant.png"
+html_favicon = "_static/img/favicon.png"
+html_extra_path = [
+    "../CNAME",
+]
+
+html_theme_options = {
+    "footer_icons": [
+        {
+            "name": "Kitware",
+            "url": "https://kitware.com/",
+            "html": "Kitware",
+            "class": "",
+        },
+        {
+            "name": "Resonant",
+            "url": "https://github.com/kitware-resonant",
+            "html": "Resonant",
+            "class": "",
+        },
+    ],
+}
+
+# Copy button customization
+# exclude traditional Python prompts from the copied code
+copybutton_prompt_text = r">>> ?|\.\.\. "
+copybutton_prompt_is_regexp = True

poetry.lock

@@ -8,7 +8,7 @@ applications with Django, Django Rest Framework (DRF), PostgreSQL, and Celery.
 Ecosystem
 ---------
 
-Functionality is broken into `many tagged repositories on GitHub <https://github.com/orgs/kitware-resonant/repositories?`_.
+Functionality is broken into `many repositories on GitHub <https://github.com/kitware-resonant>`_.
 Each does one thing well and can generally be used on its own.
 
 * `django-s3-file-field <https://github.com/kitware-resonant/django-s3-file-field>`_

pyproject.toml

@@ -0,0 +1,57 @@
+Resonant
+========
+
+.. toctree::
+   :caption: Contents
+   :hidden:
+
+   self
+
+
+.. toctree::
+   :caption: Explanation
+   :hidden:
+
+   explanation/index
+
+
+*Resonant* is the Kitware Data and Analytics team’s framework we use to create
+rich web applications and APIs tailored to specific kinds of data and tasks.
+
+
+Core Values
+-----------
+.. grid:: 1 2 2 2
+    :gutter: 2
+
+    .. grid-item-card::  Customer Intimacy
+
+        We work closely with our customers to understand their business and needs
+        to properly model their domain in the web solutions we build for them.
+
+    .. grid-item-card:: Tailored Solutions
+
+        We develop custom, bespoke applications for our customers' needs and
+        circumstances, maximizing the chance of customer success.
+
+    .. grid-item-card:: Operational Efficiency
+
+        We focus on the most pressing and important problems, and we leave the more
+        common problems to the open source software we build upon.
+
+    .. grid-item-card:: Software Sustainability
+
+        We value collaborative, long term, mutually beneficial customer
+        relationships and we let that reflect in our desire to make maintainable,
+        long-lived projects.
+
+
+Key Advantages
+--------------
+* Web framework with a focus on specialized (scientific) applications
+* Boilerplate decisions are made for you
+* Focus on the choices that are most relevant for your project’s requirements
+* Rich set of out-of-the box features: user management, authentication, etc.
+* File upload/download management to S3
+* Initial solutions to data processing
+* Template for front-end projects