From 858550ef5eb53490cc9128fa2252debc18a7f3a3 Mon Sep 17 00:00:00 2001 From: Terseus Date: Sat, 12 Nov 2022 16:35:32 +0100 Subject: [PATCH 1/6] Add docs, again Now it's in Markdown and includes the `README.md`. --- docs/conf.py | 34 ++++++++++++++++++++++++++++++++++ docs/index.md | 16 ++++++++++++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++++++ requirements-doc.txt | 3 +++ tox.ini | 6 ++++++ 5 files changed, 94 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 docs/make.bat create mode 100644 requirements-doc.txt diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..f6a4175 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,34 @@ +# 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("..")) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "io-chunks" +copyright = "2022, David Caro Martínez " +author = "David Caro Martínez " + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", +] + +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/index.md b/docs/index.md new file mode 100644 index 0000000..b1f501e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,16 @@ +% io-chunks documentation master file, created by +% sphinx-quickstart on Sat Nov 12 10:42:33 2022. +% You can adapt this file completely to your liking, but it should at least +% contain the root `toctree` directive. + +```{include} ../README.md +``` + +# API + +```{eval-rst} +.. automodule:: io_chunks + :members: + :special-members: __init__ + :inherited-members: +``` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /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=. +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/requirements-doc.txt b/requirements-doc.txt new file mode 100644 index 0000000..09c8af5 --- /dev/null +++ b/requirements-doc.txt @@ -0,0 +1,3 @@ +sphinx +myst-parser +sphinx-rtd-theme diff --git a/tox.ini b/tox.ini index 6e8ab40..d954639 100644 --- a/tox.ini +++ b/tox.ini @@ -20,6 +20,12 @@ depends = {py37, py38, py39, py310, py311}: cov-clean cov-report: py37, py38, py39, py310, py311 +[testenv:docs] +changedir = docs +deps = -rrequirements-doc.txt +skip_install = true +commands = sphinx-build -W -b html -d _build/doctrees . _build/html + [testenv:cov-report] # [toml] required for pyproject.toml support deps = coverage[toml] From 2f6c56e39c6e961ddd40c94000a8f2d5cd29dffc Mon Sep 17 00:00:00 2001 From: Terseus Date: Sun, 13 Nov 2022 10:54:49 +0100 Subject: [PATCH 2/6] Add doc build to GH actions, refactor GH actions Now we have three jobs in the main workflow: - tests - build_package - docs Let's see how it works. --- .github/workflows/main.yml | 52 ++++++++++++++++++++++++++----- .github/workflows/upload-pypi.yml | 2 +- 2 files changed, 46 insertions(+), 8 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 391b687..9a35d18 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -1,4 +1,4 @@ -name: Test +name: Validations on: push: @@ -9,8 +9,7 @@ on: - "*" jobs: - build: - + tests: runs-on: ubuntu-latest strategy: fail-fast: false @@ -28,7 +27,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - python -m pip install build tox tox-gh-actions twine + python -m pip install tox tox-gh-actions - name: Test with tox run: tox @@ -38,7 +37,46 @@ jobs: with: token: ${{ secrets.CODECOV_TOKEN }} - - name: Build wheel + build_package: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install build twine + + - name: Build wheel and sdist run: | - python -m build --wheel --sdist - twine check dist/* + python -m build --sdist --wheel --outdir dist/ + + - name: Check packages + run: twine check dist/* + + docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install tox tox-gh-actions + + - name: Build doc + run: tox -e docs diff --git a/.github/workflows/upload-pypi.yml b/.github/workflows/upload-pypi.yml index 66d7949..f148d3c 100644 --- a/.github/workflows/upload-pypi.yml +++ b/.github/workflows/upload-pypi.yml @@ -1,4 +1,4 @@ -name: Publish to https://test.pypi.org/ +name: Publish package on: push: From 5c167ec0aef1aa0a52e56107ff382afc642f3e0f Mon Sep 17 00:00:00 2001 From: Terseus Date: Sun, 13 Nov 2022 10:59:06 +0100 Subject: [PATCH 3/6] Adds the empty directory _static for sphinx --- docs/_static/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/_static/.gitkeep diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 From ecd0399e8291c94d34deee7fca7775b56a27f5cb Mon Sep 17 00:00:00 2001 From: Terseus Date: Sun, 13 Nov 2022 11:41:05 +0100 Subject: [PATCH 4/6] Add readthedocs support --- .readthedocs.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..ef67677 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,18 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-20.04 + tools: + python: "3" + +sphinx: + builder: dirhtml + configuration: docs/conf.py + +python: + install: + - requirements: requirements-doc.txt From 848fa2c98e2ab7d63577701d4596b09203dd323e Mon Sep 17 00:00:00 2001 From: Terseus Date: Sun, 13 Nov 2022 11:55:41 +0100 Subject: [PATCH 5/6] Set source_suffix in sphinx conf file Without setting it explicitly readthedocs doesn't find the `index.md` file, it tries *really, really hard* to use `index.rst` even when it doesn't exists. --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index f6a4175..bfe9312 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ "myst_parser", "sphinx.ext.autodoc", ] - +source_suffix = [".md"] templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] From 16f6f22e1fe7a7aecb4b11b2331939c3ee64f612 Mon Sep 17 00:00:00 2001 From: Terseus Date: Sun, 13 Nov 2022 16:25:10 +0100 Subject: [PATCH 6/6] Update README and CHANGELOG --- CHANGELOG.md | 1 + README.md | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index de3a54a..f5e0a49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Change `README.rst` to `README.md`. - Replace `setup.py` with `pyproject.toml`. - Renamed `chunks.py` to `raw_io_chunk.py`. +- Changed Sphinx doc to use Markdown with the [Myst parser](https://myst-parser.readthedocs.io/en/latest/). ### Fixed diff --git a/README.md b/README.md index 672de52..a4308a7 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,12 @@ with open("test_file", "rb") as file_handle: Amazing, right? +## Why? + +While writing a parser I found this class to be somewhat useful, around 7 years ago. + +While today I don't really see it today, I decided to clean it up and released it in case it's useful for someone. + ## Install Use `pip`: @@ -44,7 +50,7 @@ $ pip install io-chunks ## Documentation -Use the source, Luke! +You can read it at [readthedocs](https://python-io-chunks.readthedocs.io/en/latest/). ## Run the tests