Documentation Site

.github/workflows/quarto-pages.yml

@@ -0,0 +1,92 @@
+
+# https://jupyterbook.org/en/stable/publish/gh-pages.html
+
+name: deploy-docs-to-gh-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/**
+
+  # 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
+    #
+
+    # INSTALL PYTHON
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+
+    # INSTALL PACKAGE DEPENDENCIES (IF YOU ARE DOCUMENTING YOUR PACKAGE)
+    - name: Install dependencies
+      run: |
+        pip install -r requirements.txt
+
+    # INSTALL DOCUMENTATION DEPENDENCIES
+    - name: Install docs dependencies
+      run: |
+        pip install -r docs/requirements.txt
+
+    # TODO: adapt to use poetry instead!
+    # https://github.com/marketplace/actions/python-poetry-action
+
+
+
+
+    #
+    # 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,11 @@
+
+
+
+docs-build:
+	quartodoc build --config docs/_quarto.yml --verbose
+	quarto render docs/
+	open docs/_build/index.html
+
+docs-preview:
+	quartodoc build --config docs/_quarto.yml
+	quarto preview docs/

README.md

@@ -10,8 +10,8 @@ Currently, this tool can:
 * Pull "trending" Truth posts
 * Pull ads
 * Pull a user's metadata
-* Pull "trending" groups 
-* Pull list of suggested groups 
+* Pull "trending" groups
+* Pull list of suggested groups
 * Pull "trending" group hashtags
 * Pull posts from group timeline
 
@@ -48,7 +48,7 @@ Commands:
   user               Pull a user's metadata.
   likes              Pull the list of users who liked a post
   groupposts         Pull posts from a groups's timeline
-  grouptags         Pull trending group tags. 
+  grouptags         Pull trending group tags.
   grouptrends       Pull trending groups.
   groupsuggestions  Pull list of suggested groups.
 ``````
@@ -101,13 +101,13 @@ truthbrush grouptags
 
 **Pull trending groups**
 
-```bash 
-truthbrush grouptrends      
-``` 
+```bash
+truthbrush grouptrends
+```
 
 **Pull list of suggested groups**
 
-```bash 
+```bash
 truthbrush groupsuggestions
 ```
 

docs/.gitignore

@@ -0,0 +1 @@
+/.quarto/

docs/README.md

@@ -0,0 +1,66 @@
+# 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.9
+conda activate truthbrush-docs
+
+conda install -c conda-forge poetry
+poetry install
+
+pip install -r docs/requirements.txt # todo: use poetry instead!
+```
+
+
+
+## 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,82 @@
+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
+
+  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.userLikes", "domain": "py", "role": "function", "priority": "1", "uri": "reference/api.Api.html#truthbrush.api.Api.userLikes", "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": "-"}]}