docs: Convert to markdown (#269)

.github/workflows/publish-docs.yml

@@ -1,6 +1,9 @@
 name: Publish Docs
 
-on: [push]
+on:
+  push:
+    branches:
+      - master
 
 jobs:
   build:
@@ -14,6 +17,26 @@ jobs:
         run: |
           git config --global user.name 'travis-ci'	
           git config --global user.email 'travis@nowhere.edu'
+
+      - name: Filter changed file paths to outputs
+        uses: dorny/paths-filter@v2.7.0
+        id: changes
+        with:
+          filters: |
+            root_docs:
+              - CHANGES
+              - README.*
+            docs:
+              - 'docs/**/*.rst'
+              - 'docs/**/*.md'
+              - 'examples/**'
+            python_files:
+              - 'unihan_db/**'
+
+      - name: Should publish
+        if: steps.changes.outputs.docs == 'true' || steps.changes.outputs.root_docs == 'true' || steps.changes.outputs.python_files == 'true'
+        run: echo "PUBLISH=$(echo true)" >> $GITHUB_ENV
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v1
         with:

CHANGES

@@ -1,41 +1,41 @@
-=========
-Changelog
-=========
+# Changelog
+
+## current
 
-current
--------
 - Add latest updates here
 
-unihan-db 0.2.0 (2021-06-15)
-----------------------------
-- Update `black` to 21.6b0
+## unihan-db 0.2.0 (2021-06-15)
+
+- Update {}`black` to 21.6b0
 - Update trove classifiers to 3.9
-- :issue:`267` Drop python 2.7, 3.5. Remove unused ``__future__`` and
+- {issue}`267` Drop python 2.7, 3.5. Remove unused `__future__` and
   modesets.
 
-unihan-db 0.1.0 (2020-08-09)
-----------------------------
-- Major overhaul of docs (self-host + add icons and metadata) `#262`_
-- Move from travis to github actions `#262`_
-- Move build / publish of packaging to poetry `#263`_
+## unihan-db 0.1.0 (2020-08-09)
+
+- Major overhaul of docs (self-host + add icons and metadata) [#262][#262]
+- Move from travis to github actions [#262][#262]
+- Move build / publish of packaging to poetry [#263][#263]
 - Add README docs on publishing versions, linting, and development
-- Move from Pipfile to Poetry (https://github.com/cihai/unihan-db/pull/261)
+- Move from Pipfile to Poetry (<https://github.com/cihai/unihan-db/pull/261>)
 - Speed up importing initial data
 - Support for more fields
 - Support for appdirs (XDG directory specification)
 - Zero-config sqlite default
 - Bump unihan-etl to 0.9.5
-- Add ``project_urls`` to setup.py
-- Use ``collections`` import that's compatible with python 2 and 3
+- Add `project_urls` to setup.py
+- Use `collections` import that's compatible with python 2 and 3
 - Loosen version constraints
 
-.. _#262: https://github.com/cihai/unihan-db/pull/262
-.. _#263: https://github.com/cihai/unihan-db/pull/263
+[#262]: https://github.com/cihai/unihan-db/pull/262
+[#263]: https://github.com/cihai/unihan-db/pull/263
+
+## unihan-db 0.0.0 (2017-05-29)
 
-unihan-db 0.0.0 (2017-05-29)
-----------------------------
 This had no pypi release
 
 - Initial commit
 
-.. vim: set filetype=rst:
+<!---
+vim: set filetype=markdown:
+-->

MANIFEST.in

@@ -1,3 +1,3 @@
-include README.rst LICENSE CHANGES pyproject.toml .tmuxp.yaml
-recursive-include docs *.rst
+include README.md LICENSE CHANGES pyproject.toml .tmuxp.yaml
+recursive-include docs *.md
 recursive-include unihan_db *.py

Makefile

@@ -44,3 +44,6 @@ flake8:
 
 watch_flake8:
 	if command -v entr > /dev/null; then ${PY_FILES} | entr -c $(MAKE) flake8; else $(MAKE) flake8 entr_warn; fi
+
+format_markdown:
+	prettier --parser=markdown -w *.md docs/*.md docs/**/*.md CHANGES

README.md

@@ -0,0 +1,138 @@
+_unihan-db_ - database [SQLAlchemy](https://www.sqlalchemy.org/) models
+for [UNIHAN](http://www.unicode.org/charts/unihan.html). Part of the
+[cihai](https://cihai.git-pull.com) project. Powered by
+[unihan-etl](https://unihan-etl.git-pull.com). See also:
+[libUnihan](http://libunihan.sourceforge.net/).
+
+[![Python Package](https://img.shields.io/pypi/v/unihan-db.svg)](http://badge.fury.io/py/unihan-db)
+[![Docs](https://github.com/cihai/unihan-db/workflows/Publish%20Docs/badge.svg)](https://github.com/cihai/unihan-db/actions?query=workflow%3A%22Publish+Docs%22)
+[![Build Status](https://github.com/cihai/unihan-db/workflows/test/badge.svg)](https://github.com/cihai/unihan-db/actions?query=workflow%3A%22test%22)
+[![Code Coverage](https://codecov.io/gh/cihai/unihan-db/branch/master/graph/badge.svg)](https://codecov.io/gh/cihai/unihan-db)
+![License](https://img.shields.io/github/license/cihai/unihan-db.svg)
+
+By default, unihan-db creates a SQLite database in an [XDG data
+directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+You can specify a custom database destination by passing a database url
+into
+[get_session](http://unihan-db.git-pull.com/en/latest/api.html#unihan_db.bootstrap.get_session).
+
+# Example usage
+
+```python
+#!/usr/bin/env python
+import pprint
+
+from sqlalchemy.sql.expression import func
+
+from unihan_db import bootstrap
+from unihan_db.tables import Unhn
+
+session = bootstrap.get_session()
+
+bootstrap.bootstrap_unihan(session)
+
+random_row = session.query(Unhn).order_by(
+    func.random()
+).limit(1).first()
+
+pp = pprint.PrettyPrinter(indent=0)
+
+pp.pprint(random_row.to_dict())
+```
+
+Run:
+
+    $ ./examples/01_bootstrap.py
+
+Output:
+
+```python
+{'char': '鎷',
+'kCantonese': [{'char_id': '鎷', 'definition': 'maa5', 'id': 24035}],
+'kDefinition': [],
+'kHanYu': [{'char_id': '鎷',
+          'id': 24014,
+          'locations': [{'character': 5,
+                       'generic_indice_id': 24014,
+                       'generic_reading_id': None,
+                       'id': 42170,
+                       'page': 4237,
+                       'virtual': 0,
+                       'volume': 6}],
+          'type': 'kHanYu'}],
+'kHanyuPinyin': [{'char_id': '鎷',
+                'id': 18090,
+                'locations': [{'character': 5,
+                             'generic_indice_id': None,
+                             'generic_reading_id': 18090,
+                             'id': 42169,
+                             'page': 4237,
+                             'virtual': 0,
+                             'volume': 6}],
+                'readings': [{'generic_reading_id': 18090,
+                            'id': 26695,
+                            'reading': 'mǎ'}],
+                'type': 'kHanyuPinyin'}],
+'kMandarin': [{'char_id': '鎷', 'hans': 'mǎ', 'hant': 'mǎ', 'id': 23486}],
+'ucn': 'U+93B7'}
+```
+
+# Developing
+
+[poetry](https://python-poetry.org/) is a required package to develop.
+
+`git clone https://github.com/cihai/unihan-etl.git`
+
+`cd unihan-etl`
+
+`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)](http://eradman.com/entrproject/))
+
+## Documentation
+
+Default preview server: <http://localhost:8041>
+
+`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)](http://eradman.com/entrproject/))
+
+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](https://github.com/psf/black) and
+[isort](https://pypi.org/project/isort/) (one after the other) and runs
+[flake8](https://flake8.pycqa.org/) via CI. See the configuration in
+<span class="title-ref">pyproject.toml</span> 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.1, [poetry](https://python-poetry.org/) handles virtualenv
+creation, package requirements, versioning, building, and publishing.
+Therefore there is no setup.py or requirements files.
+
+Update <span class="title-ref">\_\_version\_\_</span> in <span
+class="title-ref">\_\_about\_\_.py</span> and \`pyproject.toml\`:
+
+    git commit -m 'build(unihan-db): Tag v0.1.1'
+    git tag v0.1.1
+    git push
+    git push --tags
+    poetry build
+    poetry deploy