Merge branch 'master' into replace_env

.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

@@ -4,6 +4,7 @@
 
 * added option to completely replace environment with contents of the dotenv
   file
+* added very simple docs for readthedocs
 
 ## [3.2.2] -- 2023-11-10
 

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)
@@ -46,6 +49,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
+
+.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
@@ -54,6 +66,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,110 @@
+# dotenv CLI
+
+Dotenv-CLI provides the `dotenv` command. `dotenv` loads the `.env` file from
+the current directory, puts the contents in the environment by either changing
+existing- or adding new environment variables, and executes the given command.
+
+`dotenv` supports alternative `.env` files like `.env.development` via the `-e`
+or `--dotenv` parameters.
+
+With the `--replace` flag, `dotenv` also provides an option to completely
+replace the environment variables with the ones from the `.env` file, allowing
+you to control exactly which environment variables are set.
+
+`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

pyproject.toml

@@ -24,17 +24,20 @@ classifiers = [
 dotenv = "dotenv_cli.cli:main"
 
 [project.urls]
+'Documentation' = 'https://dotenv-cli.readthedocs.io/'
 'Source' = 'https://github.com/venthur/dotenv-cli'
 'Changelog' = 'https://github.com/venthur/dotenv-cli/blob/master/CHANGELOG.md'
 
 [project.optional-dependencies]
 dev = [
+    "build",
+    "mkdocs",
+    "mkdocs-material",
+    "mypy",
     "pytest",
     "pytest-cov",
     "ruff",
-    "build",
     "twine",
-    "mypy"
 ]
 
 [tool.setuptools.dynamic]

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