Merge pull request #86 from historysciencelab/docs-to-mkdocs-material

Switch to using mkdocs for docs
crisishistory · Oct 25, 2023 · f761c27 · f761c27
2 parents 9a3d389 + 78be6c1
commit f761c27
Show file tree

Hide file tree

Showing 12 changed files with 56 additions and 172 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -10,23 +10,12 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
-    # You can also specify other tool versions:
-    # nodejs: "19"
-    # rust: "1.64"
-    # golang: "1.19"
+  jobs:
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      - "pip install -r docs/requirements.txt"
+      - "mkdocs build"
 
-# Build documentation in the "docs/" directory with Sphinx
-sphinx:
-   configuration: docs/source/conf.py
-
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
diff --git a/README.md b/README.md
@@ -59,7 +59,7 @@ Sample oral history interviews, some with transcripts we can work with:
 
 ## Getting Started
 
-First install the project using the installation instructions in docs/source/getting_started.rst. Then to use the command-line interface, run this in your terminal: 
+First install the project using the [installation instructions](https://historyaitoolkit.readthedocs.io/en/latest/getting-started/). Then to use the command-line interface, run this in your terminal: 
 
 ```
 hist --help

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README_link.md b/docs/README_link.md
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/getting_started.md → docs/getting-started.md b/docs/getting_started.md → docs/getting-started.md
@@ -2,7 +2,12 @@
 
 ## Prerequisites
 
-TODO: check which versions of Python this works with
+HistoryAIToolkit is confirmed to work with Python 3.10 and 3.11 on recent versions of Mac OSX and Linux. 
+
+!!! Note "If you are on another version of Python or Windows"
+
+    Please try out the project on your platform and let us know how it goes by [opening an issue](https://github.com/historysciencelab/HistoryAIToolkit/issues).
+
 
 ## For most Python users
 
@@ -72,8 +77,10 @@ Once you've installed the project, you can run the command-line interface with:
 │ --help                      Show this message and exit.
 ╰───────────────────────────────────────────────────────────────────────
 ╭─ Commands ────────────────────────────────────────────────────────────
-│ slice                   Slices an audio file into smaller audio files.
-│ transcribe              "Transcribes an audio file into text.
+│ generate-questions    Generates questions from a transcript.
+│ slice                 Slices an audio file into smaller audio files.
+│ transcribe            Transcribes an audio file into text.
+│ version               Lists the package version.
 ╰────────────────────────────────────────────────────────────────────────
 ```
 

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,5 @@
+{%
+   include-markdown "../README.md"
+   start="<!--intro-start-->"
+   end="<!--intro-end-->"
+%}
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+mkdocs-material
+mkdocs-material[imaging]
+mkdocs-include-markdown-plugin
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,28 @@
+site_name: HistoryAIToolKit
+site_url: https://historyaitoolkit.readthedocs.io/en/latest
+site_description: AI toolkit for professional and amateur historians, and for anyone who wishes to contribute to the recording of history by and for the community.
+repo_url: https://github.com/historysciencelab/HistoryAIToolkit
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.instant.prefetch
+    - search.suggest
+    - search.highlight
+    - search.share
+  icon:
+    repo: fontawesome/brands/github
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+
+plugins:
+  - search
+  - include-markdown    
+
+
+nav:
+  - Introduction: index.md
+  - "Getting Started": getting-started.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -34,10 +34,8 @@ dev = [
     "black",  # code auto-formatting
     "coverage==7.3.2",  # testing
     "mypy",  # linting
-    "myst-parser",  # markdown parsing
     "pytest",  # testing
-    "ruff",  # linting
-    "sphinx",  # documentation
+    "ruff==0.0.292",  # linting
     "pre-commit==3.4.0", # manages and maintains pre-commit hooks
 ]