Skip to content

Commit e3e8da5

Browse files
oprypinoprypin
committed
Migrate/add an API documentation site based on MkDocs
Includes version selector and auto-deployment to GitHub Pages
1 parent bd45602 commit e3e8da5

File tree

9 files changed

+249
-2
lines changed

9 files changed

+249
-2
lines changed

‎.github/workflows/deploy-docs.yml

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Deploy docs
2+
on:
3+
push:
4+
pull_request:
5+
branches: [master]
6+
jobs:
7+
build:
8+
name: Deploy docs
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Download source
12+
uses: actions/checkout@v2
13+
with:
14+
fetch-depth: 0 # Prevent shallow clone
15+
- name: Install Crystal
16+
uses: oprypin/install-crystal@v1
17+
- name: Install Python
18+
uses: actions/setup-python@v2
19+
- name: Install Python libs
20+
run: |
21+
pip install --no-deps -r docs/requirements.txt
22+
- name: Configure Git
23+
run: |
24+
git config user.name 'github-actions[bot]'
25+
git config user.email 'github-actions[bot]@users.noreply.github.com'
26+
- name: Build site
27+
run: |
28+
mkdocs build --strict
29+
- name: Deploy to gh-pages
30+
if: startsWith(github.ref, 'refs/tags/v')
31+
run: |
32+
mike deploy --push --update-aliases --prefix=api "${GITHUB_REF#refs/tags/v}" latest
33+
mike set-default --push --prefix=api "${GITHUB_REF#refs/tags/v}"

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
/docs/
21
/lib/
32
/bin/
43
/.shards/
@@ -8,3 +7,4 @@
87
# Dependencies will be locked in application that uses them
98
/shard.lock
109

10+
/site/

‎docs/SUMMARY.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
* [Home](README.md)
2+
* [DB module](DB.md)
3+
* Connection & session
4+
* [Database](DB/Database.md)
5+
* [ConnectionContext](DB/ConnectionContext.md)
6+
* [Connection](DB/Connection.md)
7+
* [Pool](DB/Pool.md)
8+
* [Stats](DB/Pool/Stats.md)
9+
* [SessionMethods](DB/SessionMethods.md)
10+
* [PreparedQuery](DB/SessionMethods/PreparedQuery.md)
11+
* [UnpreparedQuery](DB/SessionMethods/UnpreparedQuery.md)
12+
* Transaction
13+
* [Transaction](DB/Transaction.md)
14+
* [TopLevelTransaction](DB/TopLevelTransaction.md)
15+
* [SavePointTransaction](DB/SavePointTransaction.md)
16+
* [BeginTransaction](DB/BeginTransaction.md)
17+
* [QueryMethods](DB/QueryMethods.md)
18+
* [ExecResult](DB/ExecResult.md)
19+
* [ResultSet](DB/ResultSet.md)
20+
* Statement
21+
* [Statement](DB/Statement.md)
22+
* [PoolStatement](DB/PoolStatement.md)
23+
* [PoolUnpreparedStatement](DB/PoolUnpreparedStatement.md)
24+
* [PoolPreparedStatement](DB/PoolPreparedStatement.md)
25+
* [StatementMethods](DB/StatementMethods.md)
26+
* Driver
27+
* [Driver](DB/Driver.md)
28+
* [DriverSpecs](DB/DriverSpecs.md)
29+
* [ColumnDef](DB/DriverSpecs/ColumnDef.md)
30+
* [MetadataValueConverter](DB/MetadataValueConverter.md)
31+
* Serialization
32+
* [Serializable](DB/Serializable.md)
33+
* [NonStrict](DB/Serializable/NonStrict.md)
34+
* [Field](DB/Field.md)
35+
* [Mappable](DB/Mappable.md)
36+
* Miscellaneous
37+
* [Any](DB/Any.md)
38+
* [StringKeyCache](DB/StringKeyCache.md)
39+
* [Disposable](DB/Disposable.md)
40+
* Errors
41+
* [Error](DB/Error.md)
42+
* [NoResultsError](DB/NoResultsError.md)
43+
* [Rollback](DB/Rollback.md)
44+
* [MappingException](DB/MappingException.md)
45+
* [PoolResourceLost](DB/PoolResourceLost.md)
46+
* [ConnectionLost](DB/ConnectionLost.md)
47+
* [PoolResourceRefused](DB/PoolResourceRefused.md)
48+
* [ConnectionRefused](DB/ConnectionRefused.md)
49+
* [PoolRetryAttemptsExceeded](DB/PoolRetryAttemptsExceeded.md)
50+
* [PoolTimeout](DB/PoolTimeout.md)

‎docs/css/mkdocstrings.css

Whitespace-only changes.

‎docs/gen_doc_stubs.py

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Generate virtual doc files for the mkdocs site.
2+
# You can also run this script directly to actually write out those files, as a preview.
3+
4+
import mkdocs_gen_files
5+
6+
# Get the documentation root object
7+
root = mkdocs_gen_files.config['plugins']['mkdocstrings'].get_handler('crystal').collector.root
8+
9+
# For each type (e.g. "Foo::Bar")
10+
for typ in root.walk_types():
11+
# Use the file name "Foo/Bar.md"
12+
filename = '/'.join(typ.abs_id.split('::')) + '.md'
13+
# Make a file with the content "# ::: Foo::Bar\n"
14+
with mkdocs_gen_files.open(filename, 'w') as f:
15+
print(f'# ::: {typ.abs_id}', file=f)
16+
17+
with mkdocs_gen_files.open('README.md', 'w') as f, open('README.md') as in_f:
18+
f.write(in_f.read())

‎docs/requirements.in

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
mkdocs-material
2+
mkdocstrings-crystal
3+
mkdocs-gen-files
4+
mkdocs-literate-nav
5+
mkdocs-section-index
6+
git+https://github.com/jimporter/mike.git@7cff0cc9bd434ff2db8d7c8c945d2a6befcba85f

‎docs/requirements.txt

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
#
2+
# This file is autogenerated by pip-compile
3+
# To update, run:
4+
#
5+
# pip-compile requirements.in
6+
#
7+
cached-property==1.5.2
8+
# via mkdocstrings-crystal
9+
click==7.1.2
10+
# via
11+
# mkdocs
12+
# nltk
13+
future==0.18.2
14+
# via lunr
15+
glob2==0.7
16+
# via mkdocs-literate-nav
17+
jinja2==2.11.3
18+
# via
19+
# mike
20+
# mkdocs
21+
# mkdocstrings
22+
# mkdocstrings-crystal
23+
joblib==1.0.1
24+
# via nltk
25+
livereload==2.6.3
26+
# via mkdocs
27+
lunr[languages]==0.5.8
28+
# via mkdocs
29+
markdown==3.3.4
30+
# via
31+
# mkdocs
32+
# mkdocs-autorefs
33+
# mkdocs-material
34+
# mkdocstrings
35+
# pymdown-extensions
36+
markupsafe==1.1.1
37+
# via
38+
# jinja2
39+
# mkdocstrings
40+
# mkdocstrings-crystal
41+
git+https://github.com/jimporter/mike.git@7cff0cc9bd434ff2db8d7c8c945d2a6befcba85f
42+
# via -r requirements.in
43+
mkdocs-autorefs==0.1.1
44+
# via mkdocstrings
45+
mkdocs-gen-files==0.3.1
46+
# via -r requirements.in
47+
mkdocs-literate-nav==0.3.0
48+
# via -r requirements.in
49+
mkdocs-material-extensions==1.0.1
50+
# via mkdocs-material
51+
mkdocs-material==7.0.3
52+
# via
53+
# -r requirements.in
54+
# mkdocs-material-extensions
55+
mkdocs-section-index==0.2.3
56+
# via -r requirements.in
57+
mkdocs==1.1.2
58+
# via
59+
# mike
60+
# mkdocs-autorefs
61+
# mkdocs-gen-files
62+
# mkdocs-literate-nav
63+
# mkdocs-material
64+
# mkdocs-section-index
65+
# mkdocstrings
66+
mkdocstrings-crystal==0.3.1
67+
# via -r requirements.in
68+
mkdocstrings==0.15.0
69+
# via mkdocstrings-crystal
70+
nltk==3.5
71+
# via lunr
72+
pygments==2.8.0
73+
# via mkdocs-material
74+
pymdown-extensions==8.1.1
75+
# via
76+
# mkdocs-material
77+
# mkdocstrings
78+
pytkdocs==0.11.0
79+
# via mkdocstrings
80+
pyyaml==5.4.1
81+
# via
82+
# mike
83+
# mkdocs
84+
regex==2020.11.13
85+
# via nltk
86+
six==1.15.0
87+
# via
88+
# livereload
89+
# lunr
90+
tornado==6.1
91+
# via
92+
# livereload
93+
# mkdocs
94+
tqdm==4.58.0
95+
# via nltk
96+
verspec==0.1.0
97+
# via mike

‎mkdocs.yml

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
site_name: crystal-db
2+
site_url: https://oprypin.github.io/crystal-db/api/
3+
repo_url: https://github.com/oprypin/crystal-db
4+
edit_uri: blob/master/docs/
5+
use_directory_urls: false
6+
7+
theme:
8+
name: material
9+
icon:
10+
repo: fontawesome/brands/github
11+
features:
12+
- navigation.sections
13+
extra:
14+
version:
15+
provider: mike
16+
17+
extra_css:
18+
- css/mkdocstrings.css
19+
20+
plugins:
21+
- search
22+
- gen-files:
23+
scripts:
24+
- docs/gen_doc_stubs.py
25+
- mkdocstrings:
26+
default_handler: crystal
27+
watch: [src]
28+
- literate-nav:
29+
nav_file: SUMMARY.md
30+
- section-index
31+
- mike:
32+
canonical_version: latest
33+
34+
markdown_extensions:
35+
- pymdownx.highlight
36+
- pymdownx.magiclink
37+
- pymdownx.saneheaders
38+
- pymdownx.superfences
39+
- pymdownx.tasklist
40+
- deduplicate-toc
41+
- toc:
42+
permalink: "#"

‎src/db.cr

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ require "log"
55
# Individual database systems are supported by specific database driver shards.
66
#
77
# Available drivers include:
8+
#
89
# * [crystal-lang/crystal-sqlite3](https://github.com/crystal-lang/crystal-sqlite3) for SQLite
910
# * [crystal-lang/crystal-mysql](https://github.com/crystal-lang/crystal-mysql) for MySQL and MariaDB
1011
# * [will/crystal-pg](https://github.com/will/crystal-pg) for PostgreSQL
@@ -88,7 +89,7 @@ module DB
8889
alias Any = Union({{*TYPES}})
8990
{% end %}
9091

91-
# Result of a `#exec` statement.
92+
# Result of a `QueryMethods#exec` statement.
9293
record ExecResult, rows_affected : Int64, last_insert_id : Int64
9394

9495
# :nodoc:

0 commit comments

Comments
 (0)