Documentation for V Client Library (#128)

There is now a "V Client Library" page to properly document the public
interface when using V to interact with vsql.

To make this easier, a new feature has been created that will extract
"snippets" from comments in V code and put them into `snippets.rst` for
reference in the documentation. This will ensure that we only need to
keep the docs in one place right within the code.

.github/workflows/ci.yml

@@ -28,6 +28,7 @@ jobs:
         pip install sphinx sphinx_rtd_theme
         cd docs && python3 -m pip install -r requirements.txt && cd -
         make clean-docs docs
+        git diff --exit-code
 
     - name: Run SQL tests
       run: make test

.gitignore

@@ -3,3 +3,4 @@ vsql-cli
 vsql-server
 *.vsql
 .vscode
+.vlang_tmp_build/

Makefile

@@ -6,6 +6,11 @@ BUILD_OPTIONS =
 
 PROD = -prod
 
+# Ready is a some quick tasks that can easily be forgotten when preparing a
+# diff.
+
+ready: grammar fmt snippets
+
 # Binaries
 
 bin/vsql:
@@ -19,7 +24,10 @@ bin/vsql.exe:
 
 # Documentation
 
-docs:
+snippets:
+	python3 generate-snippets.py > docs/snippets.rst
+
+docs: snippets
 	mkdir -p docs/_static
 	cd docs && make html SPHINXOPTS="-W --keep-going -n"
 

README.md

@@ -10,7 +10,7 @@ database written in pure [V](https://vlang.io) with zero dependencies.
 After
 [installing or updating](https://vsql.readthedocs.io/en/latest/install.html),
 you can use vsql
-[within your V applications](https://vsql.readthedocs.io/en/latest/v-module.html),
+[within your V applications](https://vsql.readthedocs.io/en/latest/v-client-library.html),
 interact with database files using the
 [CLI](https://vsql.readthedocs.io/en/latest/cli.html), or connect to a database
 using the
@@ -21,7 +21,7 @@ or use one of the quick links:
 
 - [FAQ](https://vsql.readthedocs.io/en/latest/faq.html)
 - [CLI](https://vsql.readthedocs.io/en/latest/cli.html)
-- [Supported PostgreSQL clients](https://vsql.readthedocs.io/en/latest/supported-clients.html)
+- [Supported PostgreSQL clients](https://vsql.readthedocs.io/en/latest/postgresql-clients.html)
 - [Features](https://vsql.readthedocs.io/en/latest/features.html)
 - [SQL Reference](https://vsql.readthedocs.io/en/latest/features.html)
 - [Contributing](https://vsql.readthedocs.io/en/latest/contributing.html)

cmd/vsql/cli.v

@@ -28,17 +28,19 @@ fn cli_command(cmd cli.Command) ? {
 		if query != '' {
 			start := time.ticks()
 			result := db.query(query)?
+			mut total_rows := 0
 			for row in result {
 				for column in result.columns {
 					print('$column.name: ${row.get_string(column.name)} ')
 				}
+				total_rows++
 			}
 
-			if result.rows.len > 0 {
+			if total_rows > 0 {
 				println('')
 			}
 
-			println('$result.rows.len ${vsql.pluralize(result.rows.len, 'row')} (${time.ticks() - start} ms)')
+			println('$total_rows ${vsql.pluralize(total_rows, 'row')} (${time.ticks() - start} ms)')
 		}
 
 		println('')

docs/cli.rst

@@ -1,5 +1,5 @@
-CLI
-===
+Command Line Interface (CLI)
+============================
 
 You can also work with database files through the CLI (ctrl+c to exit):
 

docs/client-interfaces.rst

@@ -0,0 +1,9 @@
+Client Interfaces
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   cli.rst
+   postgresql-clients.rst
+   v-client-library.rst

docs/getting-started.rst

@@ -6,6 +6,3 @@ Getting Started
 
    install.rst
    faq.rst
-   v-module.rst
-   cli.rst
-   supported-clients.rst

docs/index.rst

@@ -10,6 +10,7 @@ Welcome to the vsql documentation.
    features.rst
    sql-reference.rst
    sql-language.rst
+   client-interfaces.rst
    internals.rst
    development.rst
    appendix.rst

docs/install.rst

@@ -15,4 +15,4 @@ See Also
 
 - :doc:`cli`
 - :doc:`contributing`
-- :doc:`v-module`
+- :doc:`v-client-library`

docs/supported-clients.rst → docs/postgresql-clients.rst

@@ -1,5 +1,5 @@
-Supported Clients
-=================
+PostgreSQL Clients
+==================
 
 vsql can run as a server that is compatible with PostgreSQL clients. However,
 some clients will execute complex or highly PostgreSQL-specific queries during

docs/server.rst

@@ -4,7 +4,7 @@ Server
 vsql can be run as a server and any PostgreSQL-compatible driver can access it.
 This is ideal if you want to use a more familar or feature rich database client.
 
-See the :doc:`list of supported clients here<supported-clients>`.
+See the :doc:`list of supported clients here<postgresql-clients>`.
 
 Now run it with (if the file does not exist it will be created):