From 4744ed5256c9ddbab76ed53d0044d832ce1c48df Mon Sep 17 00:00:00 2001 From: Inga Ulusoy Date: Tue, 20 Dec 2022 19:49:39 +0100 Subject: [PATCH] add sphinx documentation files (#47) * add sphinx doc * add github pages files * create docs workflow * add sphinx requirements * add napoleon ext * fix name typo --- .github/workflows/docs.yml | 31 +++++++++++++++++++ docs/.nojekyll | 0 docs/Makefile | 20 +++++++++++++ docs/index.html | 2 ++ docs/make.bat | 35 ++++++++++++++++++++++ docs/source/conf.py | 33 ++++++++++++++++++++ docs/source/index.rst | 22 ++++++++++++++ docs/source/license_link.md | 4 +++ docs/source/misinformation.rst | 55 ++++++++++++++++++++++++++++++++++ docs/source/modules.rst | 7 +++++ docs/source/readme_link.md | 2 ++ requirements-dev.txt | 4 +++ 12 files changed, 215 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/.nojekyll create mode 100644 docs/Makefile create mode 100644 docs/index.html create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/license_link.md create mode 100644 docs/source/misinformation.rst create mode 100644 docs/source/modules.rst create mode 100644 docs/source/readme_link.md create mode 100644 requirements-dev.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..128eaa7 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,31 @@ +name: Pages + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/setup-python@v4 + with: + python-version: '3.9' + - uses: actions/checkout@v3 + with: + fetch-depth: 0 # otherwise, you will failed to push refs to dest repo + - name: install misinformation + run: | + pip install -e . + python -m pip install -r requirements-dev.txt + - name: Build documentation + run: | + cd docs + make html + - name: Push changes to gh-pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs # The folder the action should deploy. diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..50b8466 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,2 @@ + + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..d4dd3e2 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,33 @@ +# 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 + +import os +import sys + +sys.path.insert(0, os.path.abspath("../../misinformation/")) + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "misinformation" +copyright = "2022, Scientific Software Center, Heidelberg University" +author = "Scientific Software Center, Heidelberg University" +release = "0.0.1" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "myst_parser"] + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..fd09508 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,22 @@ +.. misinformation documentation master file, created by + sphinx-quickstart on Mon Dec 19 13:39:22 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to misinformation's documentation! +========================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + readme_link + modules + license_link + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/license_link.md b/docs/source/license_link.md new file mode 100644 index 0000000..fd61174 --- /dev/null +++ b/docs/source/license_link.md @@ -0,0 +1,4 @@ +# License + +```{include} ../../LICENSE +``` \ No newline at end of file diff --git a/docs/source/misinformation.rst b/docs/source/misinformation.rst new file mode 100644 index 0000000..c0b4d61 --- /dev/null +++ b/docs/source/misinformation.rst @@ -0,0 +1,55 @@ +utils module +------------ + +.. automodule:: utils + :members: + :undoc-members: + :show-inheritance: + +display module +-------------- + +.. automodule:: display + :members: + :undoc-members: + :show-inheritance: + +faces module +------------ + +.. automodule:: faces + :members: + :undoc-members: + :show-inheritance: + +objects_cvlib module +-------------------- + +.. automodule:: objects_cvlib + :members: + :undoc-members: + :show-inheritance: + +objects module +-------------- + +.. automodule:: objects + :members: + :undoc-members: + :show-inheritance: + +text module +----------- + +.. automodule:: text + :members: + :undoc-members: + :show-inheritance: + +cropposts module +---------------- + +.. automodule:: cropposts + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..114acf1 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +misinformation package modules +============================== + +.. toctree:: + :maxdepth: 4 + + misinformation \ No newline at end of file diff --git a/docs/source/readme_link.md b/docs/source/readme_link.md new file mode 100644 index 0000000..060259b --- /dev/null +++ b/docs/source/readme_link.md @@ -0,0 +1,2 @@ +```{include} ../../README.md +``` \ No newline at end of file diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..361d4f4 --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,4 @@ +sphinx +myst-parser +sphinx_rtd_theme +sphinxcontrib-napoleon \ No newline at end of file