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: 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 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 diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..bfe9312 --- /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", +] +source_suffix = [".md"] +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]