Documentation Site

.github/workflows/python-app.yml

@@ -0,0 +1,68 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
+
+name: Python application
+
+on:
+  push:
+    #branches: [ "main" ]
+  #pull_request:
+    #branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    # PYTHON
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+
+    # INSTALL PACKAGES
+
+    #- name: Install dependencies
+    #  run: |
+    #    python -m pip install --upgrade pip
+    #    pip install flake8 pytest
+    #    if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+
+    # TODO: use poetry instead!
+    # poetry install --with test,docs
+
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+
+    - name: Install dependencies with Poetry
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 pytest
+        poetry --version
+        poetry install
+
+    # LINTING
+
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+    # TESTS
+
+    - name: Test with pytest
+      env:
+        # set environment variable to use during testing
+        TRUTHSOCIAL_USERNAME: ${{ secrets.TRUTHSOCIAL_USERNAME }}
+        TRUTHSOCIAL_PASSWORD: ${{ secrets.TRUTHSOCIAL_PASSWORD }}
+      run: |
+        poetry run pytest

.github/workflows/quarto-pages.yml

@@ -0,0 +1,103 @@
+
+# https://jupyterbook.org/en/stable/publish/gh-pages.html
+
+name: quarto-pages
+
+on:
+  push:
+    #branches:
+    #- main
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder has been modified.
+    #
+    #paths:
+    #- docs/**
+
+  #pull_request:
+    #branches: [ "main" ]
+
+  # make this workflow manually runnable
+  # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch
+  workflow_dispatch:
+
+
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v3
+
+    #
+    # PYTHON STUFF
+    #
+
+    - name: Install Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+
+    # PACKAGE DEPENDENCIES
+
+    #- name: Install dependencies
+    #  run: |
+    #    pip install -r requirements.txt
+
+    # INSTALL DOCUMENTATION DEPENDENCIES
+    #- name: Install docs dependencies
+    #  run: |
+    #    pip install -r docs/requirements.txt
+
+    # TODO: use poetry instead!
+    # https://github.com/marketplace/actions/python-poetry-action
+    # poetry install --with test,docs
+
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+
+    # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+    - name: Install dependencies with Poetry
+      run: |
+        poetry install --with docs
+
+
+
+    #
+    # QUARTO STUFF
+    #
+
+    # INSTALL QUARTO
+    # https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml
+    - name: Set up Quarto
+      uses: quarto-dev/quarto-actions/setup@v2
+      #env:
+      #  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        # To install LaTeX to build PDF book
+        # (to get past errors on the CI build)
+        tinytex: true
+        # uncomment below and fill to pin a version
+        # version: SPECIFIC-QUARTO-VERSION-HERE
+
+    # RENDER WEBSITE CONTENTS TO DOCS/_BUILD
+    - name: Build the docs
+      run: |
+        quarto render docs/
+
+    #
+    # GITHUB PAGES STUFF
+    #
+
+    # UPLOAD CONTENTS OF DOCS/_BUILD
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: "docs/_build"
+
+    # DEPLOY WEBSITE CONTENTS TO GITHUB PAGES
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v2

Makefile

@@ -0,0 +1,16 @@
+
+
+
+build-docs:
+	rm -rf docs/reference
+	quartodoc build --config docs/_quarto.yml --verbose
+	quarto render docs/
+#	open docs/_build/index.html
+
+open-docs:
+	open docs/_build/index.html
+
+preview-docs:
+	rm -rf docs/reference
+	quartodoc build --config docs/_quarto.yml
+	quarto preview docs/

README.md

@@ -143,7 +143,7 @@ truthbrush --help # will use your local copy of truthbrush
 If you prefer not to install Poetry in your root environment, you can also use Conda:
 
 ```sh
-conda create -n truthbrush-env python=3.9
+conda create -n truthbrush-env python=3.10
 conda activate truthbrush-env
 
 conda install -c conda-forge poetry
@@ -157,6 +157,9 @@ pytest
 
 # optionally run tests with verbose logging outputs:
 pytest --log-cli-level=DEBUG -s
+
+# optionally run tests with suppressed warnings:
+pytest --disable-pytest-warnings
 ```
 
 Please format your code with `black`:
@@ -165,6 +168,11 @@ Please format your code with `black`:
 black .
 ```
 
+### Continuous Integration
+
+The Continuous Integration build on GitHub Actions is controlled via the "python-app" workflow file. To make the build pass, the environment variables `TRUTHSOCIAL_USERNAME` and `TRUTHSOCIAL_PASSWORD` must be set as GitHub repository secrets.
+
+
 ## Wishlist
 
 Support for the following capabilities is planned:

docs/.gitignore

@@ -0,0 +1,3 @@
+/.quarto/
+
+*.html

docs/README.md

@@ -0,0 +1,64 @@
+# Truthbrush Documentation Site
+
+## Prerequisites
+
+### Quarto
+
+The documentation site is built using [Quarto](https://quarto.org/). Quarto can be [downloaded](https://quarto.org/docs/get-started/), or [installed via homebrew](https://formulae.brew.sh/cask/quarto) (if you like that kind of thing):
+
+```sh
+brew install --cask quarto
+```
+
+If you use VS Code, you can also consider installing the [Quarto Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto).
+
+
+## Docs Environment
+
+Setup environment and install package dependencies:
+
+```sh
+conda create -n truthbrush-docs python=3.10
+conda activate truthbrush-docs
+
+conda install -c conda-forge poetry
+poetry install --with docs
+```
+
+
+
+## Auto Documentation
+
+In the "quartodoc" section of the ["_quarto.yml" config file](/docs/_quarto.yml), we specify that our site should display "references/index.qmd", which acts as the entrypoint into the package auto-documentation.
+
+We are using [quartodoc](https://machow.github.io/quartodoc/get-started/basic-docs.html) to automatically generate docstring content into the "docs/references" directory:
+
+```sh
+quartodoc build --config docs/_quarto.yml --verbose
+```
+
+After the documentation pages have been generated, then we can preview and build the site.
+
+
+## Building
+
+
+Previewing the site (runs like a local webserver):
+
+```sh
+quarto preview docs/
+```
+
+
+Rendering the site (writes local HTML files to the "docs/_build" directory, which is ignored from version control):
+
+```sh
+quarto render docs/ --verbose
+```
+
+
+### Website Publishing
+
+We are using the ["quarto-pages.yml" workflow configuration file](/.github/workflows/quarto-pages.yml) to deploy the site to GitHub Pages when new commits are pushed to the main branch.
+
+In order for this to work, the GitHub Pages repo settings need to be configured to publish via GitHub Actions.

docs/_quarto.yml

@@ -0,0 +1,84 @@
+project:
+  type: website
+  output-dir: _build
+  preview:
+    #port: 5554 # use the same port instead of a new one each time
+    browser: true
+
+website:
+  title: "Truthbrush Documentation Site"
+
+  site-url: https://stanfordio.github.io/truthbrush/
+  repo-url: https://github.com/stanfordio/truthbrush
+  repo-branch: main
+  repo-subdir: docs
+  repo-actions: [edit, issue, source]
+
+  search: true
+  page-navigation: true # adds buttons at bottom of page
+
+  navbar:
+    right:
+      - href: index.qmd
+        text: Home
+      - about.qmd
+
+  sidebar:
+    contents:
+      - href: index.qmd
+        text: Home
+
+      - section:
+        href: reference/index.qmd
+        title: "Truthbrush Package Reference"
+        contents:
+          - href: reference/api.Api.qmd
+            text: "API Reference"
+          - href: reference/cli.qmd
+            text: "CLI Reference"
+
+
+
+format:
+  html:
+    theme: cosmo
+    css: styles.css
+    toc: true
+    #code-copy: true
+
+
+#
+# PYTHON PACKAGE AUTO-DOCUMENTATION
+#
+
+# https://machow.github.io/quartodoc/get-started/basic-docs.html
+quartodoc:
+  # the name used to import the package you want to create reference docs for
+  package: truthbrush
+  #version: "v1.0.1"
+
+  # directory relative to current (docs/)
+  dir: reference
+
+  #style: pkgdown
+
+  parser: google # "numpy" or "google" or "sphinx"
+
+  title: Truthbrush Package Reference
+
+  sections:
+    - title: API Reference
+      desc: Functions related to the Python API.
+      contents:
+        - api.Api
+
+    #- title: API Reference
+    #  desc: Functions related to the Python API.
+    #  package: truthbrush.api
+    #  contents:
+    #    - Api
+
+    - title: CLI Reference
+      desc: Functions related to the command line interface (CLI).
+      contents:
+        - cli

docs/about.qmd

@@ -0,0 +1,5 @@
+---
+title: "About"
+---
+
+About this site

docs/index.qmd

@@ -0,0 +1,7 @@
+---
+title: "Docs"
+---
+
+This is a Quarto website.
+
+To learn more about Quarto websites visit <https://quarto.org/docs/websites>.

docs/objects.json

@@ -0,0 +1 @@
+{"project": "truthbrush", "version": "0.0.9999", "count": 27, "items": [{"name": "truthbrush.api.Api.ads", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.ads", "dispname": "-"}, {"name": "truthbrush.api.Api.get_auth_id", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.get_auth_id", "dispname": "-"}, {"name": "truthbrush.api.Api.group_tags", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.group_tags", "dispname": "-"}, {"name": "truthbrush.api.Api.lookup", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.lookup", "dispname": "-"}, {"name": "truthbrush.api.Api.pull_statuses", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.pull_statuses", "dispname": "-"}, {"name": "truthbrush.api.Api.search", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.search", "dispname": "-"}, {"name": "truthbrush.api.Api.suggested", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.suggested", "dispname": "-"}, {"name": "truthbrush.api.Api.suggested_groups", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.suggested_groups", "dispname": "-"}, {"name": "truthbrush.api.Api.tags", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.tags", "dispname": "-"}, {"name": "truthbrush.api.Api.trending", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.trending", "dispname": "-"}, {"name": "truthbrush.api.Api.trending_groups", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.trending_groups", "dispname": "-"}, {"name": "truthbrush.api.Api.user_likes", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.user_likes", "dispname": "-"}, {"name": "truthbrush.api.Api", "domain": "py", "role": "class", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api", "dispname": "-"}, {"name": "truthbrush.cli.ads", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.ads", "dispname": "-"}, {"name": "truthbrush.cli.cli", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.cli", "dispname": "-"}, {"name": "truthbrush.cli.groupposts", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.groupposts", "dispname": "-"}, {"name": "truthbrush.cli.groupsuggest", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.groupsuggest", "dispname": "-"}, {"name": "truthbrush.cli.grouptags", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.grouptags", "dispname": "-"}, {"name": "truthbrush.cli.grouptrends", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.grouptrends", "dispname": "-"}, {"name": "truthbrush.cli.likes", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.likes", "dispname": "-"}, {"name": "truthbrush.cli.search", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.search", "dispname": "-"}, {"name": "truthbrush.cli.statuses", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.statuses", "dispname": "-"}, {"name": "truthbrush.cli.suggestions", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.suggestions", "dispname": "-"}, {"name": "truthbrush.cli.tags", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.tags", "dispname": "-"}, {"name": "truthbrush.cli.trends", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.trends", "dispname": "-"}, {"name": "truthbrush.cli.user", "domain": "py", "role": "function", "priority": "1", "uri": "reference/cli.html#truthbrush.cli.user", "dispname": "-"}, {"name": "truthbrush.cli", "domain": "py", "role": "module", "priority": "1", "uri": "reference/cli.html#truthbrush.cli", "dispname": "-"}]}