docs(contributing): Add internals and workflow

Author: tony

docs/contributing/index.md

@@ -4,71 +4,10 @@
 
 # Contributing
 
-## Development environment
+As an open source project, libvcs accepts contributions through GitHub. Below you will find
+resources on the internals of the project.
 
-[poetry] is a required package to develop.
-
-```
-git clone https://github.com/vcs-python/libvcs.git
-cd libvcs
-poetry install -E "docs test coverage lint format"
-```
-
-Makefile commands prefixed with `watch_` will watch files and rerun.
-
-## Tests
-
-```
-poetry run py.test
+```{toctree}
+workflow
+internals
 ```
-
-Helpers: `make test` Rerun tests on file change: `make watch_test` (requires [entr(1)])
-
-## Documentation
-
-Default preview server: http://localhost:8068
-
-[sphinx-autobuild] will automatically build the docs, watch for file changes and launch a server.
-
-From home directory: `make start_docs` From inside `docs/`: `make start`
-
-[sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild
-
-### Manual documentation (the hard way)
-
-`cd docs/` and `make html` to build. `make serve` to start http server.
-
-Helpers: `make build_docs`, `make serve_docs`
-
-Rebuild docs on file change: `make watch_docs` (requires [entr(1)])
-
-Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a `make(1)` with
-`-J` support, e.g. GNU Make)
-
-## Formatting / Linting
-
-The project uses [black] and [isort] (one after the other) and runs [flake8] via CI. See the
-configuration in `pyproject.toml` and `setup.cfg`:
-
-`make black isort`: Run `black` first, then `isort` to handle import nuances `make flake8`, to watch
-(requires `entr(1)`): `make watch_flake8`
-
-## Releasing
-
-As of 0.10, [poetry] handles virtualenv creation, package requirements, versioning, building, and
-publishing. Therefore there is no setup.py or requirements files.
-
-Update `__version__` in `__about__.py` and `pyproject.toml`::
-
-    git commit -m 'build(libvcs): Tag v0.1.1'
-    git tag v0.1.1
-    git push
-    git push --tags
-    poetry build
-    poetry publish
-
-[poetry]: https://python-poetry.org/
-[entr(1)]: http://eradman.com/entrproject/
-[black]: https://github.com/psf/black
-[isort]: https://pypi.org/project/isort/
-[flake8]: https://flake8.pycqa.org/

docs/contributing/internals.md

@@ -0,0 +1,20 @@
+(internals)=
+
+# Internals
+
+:::{warning}
+
+Internal APIs can break at any time and are not covered by semantic versioning or any other
+stability policy.
+
+:::
+
+```{eval-rst}
+.. autoapimodule:: libvcs.exc
+   :members:
+```
+
+```{eval-rst}
+.. autoapimodule:: libvcs.types
+   :members:
+```

docs/contributing/workflow.md

@@ -0,0 +1,72 @@
+(workflow)=
+
+# Workflow
+
+## Development environment
+
+[poetry] is a required package to develop.
+
+```
+git clone https://github.com/vcs-python/libvcs.git
+cd libvcs
+poetry install -E "docs test coverage lint format"
+```
+
+Makefile commands prefixed with `watch_` will watch files and rerun.
+
+## Tests
+
+```
+poetry run py.test
+```
+
+Helpers: `make test` Rerun tests on file change: `make watch_test` (requires [entr(1)])
+
+## Documentation
+
+Default preview server: http://localhost:8068
+
+[sphinx-autobuild] will automatically build the docs, watch for file changes and launch a server.
+
+From home directory: `make start_docs` From inside `docs/`: `make start`
+
+[sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild
+
+### Manual documentation (the hard way)
+
+`cd docs/` and `make html` to build. `make serve` to start http server.
+
+Helpers: `make build_docs`, `make serve_docs`
+
+Rebuild docs on file change: `make watch_docs` (requires [entr(1)])
+
+Rebuild docs and run server via one terminal: `make dev_docs` (requires above, and a `make(1)` with
+`-J` support, e.g. GNU Make)
+
+## Formatting / Linting
+
+The project uses [black] and [isort] (one after the other) and runs [flake8] via CI. See the
+configuration in `pyproject.toml` and `setup.cfg`:
+
+`make black isort`: Run `black` first, then `isort` to handle import nuances `make flake8`, to watch
+(requires `entr(1)`): `make watch_flake8`
+
+## Releasing
+
+As of 0.10, [poetry] handles virtualenv creation, package requirements, versioning, building, and
+publishing. Therefore there is no setup.py or requirements files.
+
+Update `__version__` in `__about__.py` and `pyproject.toml`::
+
+    git commit -m 'build(libvcs): Tag v0.1.1'
+    git tag v0.1.1
+    git push
+    git push --tags
+    poetry build
+    poetry publish
+
+[poetry]: https://python-poetry.org/
+[entr(1)]: http://eradman.com/entrproject/
+[black]: https://github.com/psf/black
+[isort]: https://pypi.org/project/isort/
+[flake8]: https://flake8.pycqa.org/