Created documentation page

.github/workflows/docs-build.yml

@@ -0,0 +1,55 @@
+name: docs-build
+
+on:
+  push:
+    branches:
+        - master
+  pull_request:
+    branches-ignore: [gh-pages]
+    paths: ['docs/**']
+
+jobs:
+  docs-build:
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.10'
+
+    - name: Install python dependencies
+      run: |
+        pip install --upgrade pip
+        pip install -e .[docs]
+
+    - name: Build HTML docs
+      id: linkcheck
+      run: |
+        make -C docs html linkcheck 2>&1 | tee check.log
+        echo "broken=$(grep '(line\s*[0-9]*)\(\s\)broken\(\s\)' check.log)" >> $GITHUB_OUTPUT
+      env:
+        SPHINXOPTS: -nW --keep-going
+
+    - name: Show docs build check results
+      run: |
+        if [ -z "${{ steps.linkcheck.outputs.broken }}" ]; then
+            echo "No broken links found."
+            exit 0
+        else
+            echo "Broken links found:"
+            echo "${{ steps.linkcheck.outputs.broken }}"
+            exit 1
+        fi
+
+    - name: Deploy docs to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_branch: gh-pages
+        publish_dir: docs/build/html
+        force_orphan: true

README.md

@@ -6,6 +6,8 @@ The OCR and translation is performed using freely available machine learning mod
 
 The server is designed to be used together with [this browser extension](https://github.com/Crivella/ocr_extension), acting as a front-end providing the images and controlling the model languages and models being used.
 
+[Full Documentation](https://crivella.github.io/ocr_translate/)
+
 ## Running the server
 
 If you plan to use a different settings (eg. database, or model location), you can either:
@@ -203,7 +205,7 @@ The second section of variables is defined at the project level and is only avai
 | --- | --- | --- |
 | `LOAD_ON_START`| false[/true] | Will automatically load the most used source/destination languages and most used models for that language combination at server start|
 | `AUTOCREATE_LANGUAGES` | false[/true] | Will automatically create the Language entries in the database as defined in [languages.json](ocr_translate/OCR_TSL/languages.json) |
-| `AUTOCREATE_VALIDATED_MODELS` | false[/true] | Will automatically create the model entries that have been tested and defined in [models.json](ocr_translate/OCR_TSL/models.json). NOTE: Creation of the models requires the involved languages to already exist in the database |
+| `AUTOCREATE_VALIDATED_MODELS` | false[/true] | Will automatically create the model entries defined in code and plugins `entrypoints`. |
 | `DEVICE` | cpu[/cuda] | Which device to use with torch |
 | `EASYOCR_MODULE_PATH` | `$HOME/.EasyOCR` | Directory where EasyOCR store its downloaded models |
 | `TRANSFORMERS_CACHE` | `$HOME/.cache/huggingface/hub/` | Directory where [Hugging Face](https://huggingface.co/) models are being stored (either downloaded manually or downloaded by `transformers`) |

docs/Makefile

@@ -0,0 +1,20 @@
+# 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     = source
+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)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+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

docs/source/conf.py

@@ -0,0 +1,39 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'ocr_translate'
+copyright = '2023, Davide Grassano'
+author = 'Davide Grassano'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.extlinks',
+    'sphinx_design',
+    'sphinx_rtd_dark_mode',
+    'sphinxcontrib.openapi',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for extlinks extension -------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html#module-sphinx.ext.extlinks
+extlinks = {
+    'github': ('https://github.com/Crivella/ocr_translate/%s', ''),
+    'dockerhub': ('https://hub.docker.com/r/crivella1/ocr_translate/%s', ''),
+}
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+default_dark_mode = True
+html_theme = 'rtd'
+html_static_path = ['_static']

docs/source/contrib/api.rst

@@ -0,0 +1,4 @@
+API Endpoints
+=============
+
+.. openapi:: ../../../openapi.yml

docs/source/contrib/index.rst

@@ -0,0 +1,61 @@
+Contributor's guide
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   plugins
+   api
+
+This is the guide for contributing to the main codebase of the project.
+
+Development dependencies
+------------------------
+
+When installing the python package with pip you can install various sets of optional dependencies.
+For development you should install django-ocr_translate (from inside a clone of your fork) with the following:
+
+.. code-block:: shell
+
+   pip install .[tests,pre-commit]
+
+If you also plan to add to the documentation than you should install the `docs` dependencies:
+
+.. code-block:: shell
+
+   pip install .[docs]
+
+pre-commit hooks
+----------------
+
+Once the python extra dependencies are installed, install the `pre-commit <https://pre-commit.com/>`_ hooks into your repo. These are used to enforce code style and run tests before commits. (This will be enforced on pull requests by the CI workflow, so you might as well do it from the beginning)
+
+.. code-block:: shell
+
+   pre-commit install
+
+You can also manually run the pre-commit command on all files:
+
+.. code-block:: shell
+
+   pre-commit run --all-files
+
+Note that some of the hooks will modify the files in place, so you might need to re-add them to the staging area.
+
+Testing
+-------
+
+If you are adding new code to the codebase, make sure to add tests for it.
+You can check if your code is covered by tests by running:
+
+.. code-block:: shell
+
+   pytest --cov=ocr_translate --cov-report=html tests
+
+And opening the `htmlcov/index.html` file generated in your working direcotry.
+
+If you are running tests with and IDE like VSCode, make sure that the following is set in your environment.
+
+.. code-block::
+
+   `DJANGO_SETTINGS_MODULE = "mysite.settings"`