diff --git a/.readthedocs.yaml b/.readthedocs.yaml index dad7a17..6dc9948 100644 --- 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 index 4574871..53bea9c 100644 --- 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 deleted file mode 100644 index d4bb2cb..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README_link.md b/docs/README_link.md deleted file mode 100644 index d9d7fbd..0000000 --- a/docs/README_link.md +++ /dev/null @@ -1,5 +0,0 @@ - - -```{include} ../README.md - -``` \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 8ca77a5..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,57 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = 'HistoryAIToolkit' -copyright = '2023, Audrey Roy Greenfeld and contributors' -author = 'Audrey Roy Greenfeld and contributors' - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# 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'] - - -# -- 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 = 'alabaster' - -# 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'] - - -# Myst configuration -extensions = ["myst_parser"] -myst_enable_extensions = ["colon_fence"] \ No newline at end of file diff --git a/docs/getting_started.md b/docs/getting-started.md similarity index 83% rename from docs/getting_started.md rename to docs/getting-started.md index b000f18..806841d 100644 --- a/docs/getting_started.md +++ b/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 new file mode 100644 index 0000000..6627327 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,5 @@ +{% + include-markdown "../README.md" + start="" + end="" +%} \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 6925f4d..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. HistoryAIToolKit documentation master file, created by - sphinx-quickstart on Mon Sep 25 13:01:57 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to HistoryAIToolKit's documentation! -============================================ - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - - -Contents: - -.. toctree:: - :maxdepth: 2 - :glob: - - README_link.md - getting_started.md diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 32bb245..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..a396279 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +mkdocs-material +mkdocs-material[imaging] +mkdocs-include-markdown-plugin \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..e01cffc --- /dev/null +++ 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 \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 46c3f44..6035600 100644 --- 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 ]