added readthedocs

.gitignore

@@ -9,6 +9,8 @@ htmlcov/
 .mypy_cache/
 .pytest_cache/
 
+site/
+
 venv/
 
 .idea/

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+mkdocs:
+  configuration: mkdocs.yml
+
+# 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: requirements-dev.txt

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [unreleased]
+
+* added very simple docs for readthedocs
+
 ## [3.2.2] -- 2023-11-10
 
 * replaced flake8 with ruff

Makefile

@@ -3,14 +3,17 @@ PY = python3
 VENV = venv
 BIN=$(VENV)/bin
 
+DOCS_SRC = docs
+DOCS_OUT = site
+
 ifeq ($(OS), Windows_NT)
 	BIN=$(VENV)/Scripts
 	PY=python
 endif
 
 
 .PHONY: all
-all: lint mypy test test-release
+all: lint mypy test test-docs test-release
 
 $(VENV): requirements-dev.txt pyproject.toml
 	$(PY) -m venv $(VENV)
@@ -43,6 +46,15 @@ test-release: $(VENV) build
 release: $(VENV) build
 	$(BIN)/twine upload dist/*
 
+.PHONY: test-docs
+test-docs: $(VENV)
+	# we try to keep the README and the docs/index.md in sync
+	@cmp README.md docs/index.md || echo "README.md and docs/index.md are not in sync"
+
+.PHONY: docs
+docs: $(VENV)
+	$(BIN)/mkdocs build
+
 VERSION = $(shell python3 -c 'from dotenv_cli import __VERSION__; print(__VERSION__)')
 tarball:
 	git archive --output=../dotenv-cli_$(VERSION).orig.tar.gz HEAD
@@ -51,6 +63,7 @@ tarball:
 clean:
 	rm -rf build dist *.egg-info
 	rm -rf $(VENV)
+	rm -rf $(DOCS_OUT)
 	find . -type f -name *.pyc -delete
 	find . -type d -name __pycache__ -delete
 	# coverage

docs/index.md

@@ -0,0 +1,106 @@
+# dotenv CLI
+
+Dotenv-CLI is a simple package that provides the `dotenv` command. It reads the
+`.env` file from the current directory puts the contents in the environment and
+executes the given command.
+
+`dotenv` supports alternative `.env` files like `.env.development` via the `-e`
+or `--dotenv` parametes.
+
+`dotenv` provides bash completion, so you can use `dotenv` like this:
+
+```bash
+$ dotenv make <TAB>
+all      clean    docs     lint     release  test
+```
+
+## Install
+
+### Using PyPi
+
+dotenv-cli is [available on PyPi][pypi], you can install it via:
+
+[pypi]: https://pypi.org/project/dotenv-cli/
+
+```bash
+$ pip install dotenv-cli
+```
+
+### On Debian and Ubuntu
+
+Alternatively, you can install dotenv-cli on Debian based distributions via:
+
+```bash
+# apt-get install python3-dotenv-cli
+```
+
+
+## Usage
+
+Create an `.env` file in the root of your project and populate it with some
+values like so:
+
+```sh
+SOME_SECRET=donttrythisathome
+SOME_CONFIG=foo
+```
+
+Just prepend the command you want to run with the extra environment variables
+from the `.env` file with `dotenv`:
+
+```bash
+$ dotenv some-command
+```
+
+and those variables will be available in your environment variables.
+
+
+## Rules
+
+The parser understands the following:
+
+* Basic unquoted values (`BASIC=basic basic`)
+* Lines starting with `export` (`export EXPORT=foo`), so you can `source` the
+  file in bash
+* Lines starting with `#` are ignored (`# Comment`)
+* Empty values (`EMPTY=`) become empty strings
+* Inner quotes are maintained in basic values: `INNER_QUOTES=this 'is' a test`
+  or `INNER_QUOTES2=this "is" a test`
+* White spaces are trimmed from unquoted values: `TRIM_WHITESPACE=  foo  ` and
+  maintained in quoted values:  `KEEP_WHITESPACE="  foo  "`
+* Interpret escapes (e.g. `\n`) in double quoted values, keep them as-is in
+  single quoted values.
+
+Example `.env` file:
+
+```sh
+BASIC=basic basic
+export EXPORT=foo
+EMPTY=
+INNER_QUOTES=this 'is' a test
+INNER_QUOTES2=this "is" a test
+TRIM_WHITESPACE= foo
+KEEP_WHITESPACE="  foo  "
+MULTILINE_DQ="multi\nline"
+MULTILINE_SQ='multi\nline'
+MULTILINE_NQ=multi\nline
+#
+# some comment
+```
+
+becomes:
+
+```sh
+$ dotenv env
+BASIC=basic basic
+EXPORT=foo
+EMPTY=
+INNER_QUOTES=this 'is' a test
+INNER_QUOTES2=this "is" a test
+TRIM_WHITESPACE=foo
+KEEP_WHITESPACE=  foo
+MULTILINE_DQ=multi
+line
+MULTILINE_SQ=multi\nline
+MULTILINE_NQ=multi\nline
+```

mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: dotenv-cli
+site_url: https://dotenv-cli.readthedocs.io/
+repo_url: https://github.com/venthur/dotenv-cli
+repo_name: venthur/dotenv-cli
+
+theme:
+  name: material

requirements-dev.txt

@@ -1,6 +1,8 @@
-twine==5.0.0
 build==1.1.1
-pytest==8.1.1
+mkdocs-material==9.5.17
+mkdocs==1.5.3
+mypy==1.9.0
 pytest-cov==4.1.0
+pytest==8.1.1
 ruff==0.3.4
-mypy==1.9.0
+twine==5.0.0