From ad001a802237bf0c61ac49faadffb1e740f874db Mon Sep 17 00:00:00 2001 From: Vikash Singh <3116482+vi3k6i5@users.noreply.github.com> Date: Tue, 6 Apr 2021 09:43:39 +0530 Subject: [PATCH 1/3] feat: updated nox file for docs and docfx and added unit tests for client --- .gitignore | 3 +- django_spanner/functions.py | 1 + django_spanner/introspection.py | 1 + django_spanner/operations.py | 5 +- django_spanner/schema.py | 1 + docs/conf.py | 43 +++++++------- noxfile.py | 76 +++++++++++++++++++++--- tests/unit/django_spanner/test_base.py | 18 ++++-- tests/unit/django_spanner/test_client.py | 44 ++++++++++++++ 9 files changed, 156 insertions(+), 36 deletions(-) create mode 100644 tests/unit/django_spanner/test_client.py diff --git a/.gitignore b/.gitignore index efe8469b33..4a39372126 100644 --- a/.gitignore +++ b/.gitignore @@ -12,7 +12,8 @@ bin MANIFEST django_tests __pycache__ - +# The directory into which Django has been cloned to run the test suite. +django_tests_dir # Unit test / coverage reports .coverage .nox diff --git a/django_spanner/functions.py b/django_spanner/functions.py index bc02d0b5d8..3cf3ec73b9 100644 --- a/django_spanner/functions.py +++ b/django_spanner/functions.py @@ -28,6 +28,7 @@ class IfNull(Func): """Represent SQL `IFNULL` function.""" + function = "IFNULL" arity = 2 diff --git a/django_spanner/introspection.py b/django_spanner/introspection.py index 2dd7341972..9cefd0687f 100644 --- a/django_spanner/introspection.py +++ b/django_spanner/introspection.py @@ -15,6 +15,7 @@ class DatabaseIntrospection(BaseDatabaseIntrospection): """A Spanner-specific version of Django introspection utilities.""" + data_types_reverse = { TypeCode.BOOL: "BooleanField", TypeCode.BYTES: "BinaryField", diff --git a/django_spanner/operations.py b/django_spanner/operations.py index 6ce0260c81..e3ff7471ec 100644 --- a/django_spanner/operations.py +++ b/django_spanner/operations.py @@ -25,6 +25,7 @@ class DatabaseOperations(BaseDatabaseOperations): """A Spanner-specific version of Django database operations.""" + cast_data_types = {"CharField": "STRING", "TextField": "STRING"} cast_char_field_without_max_length = "STRING" compiler_module = "django_spanner.compiler" @@ -108,7 +109,9 @@ def bulk_insert_sql(self, fields, placeholder_rows): values_sql = ", ".join("(%s)" % sql for sql in placeholder_rows_sql) return "VALUES " + values_sql - def sql_flush(self, style, tables, reset_sequences=False, allow_cascade=False): + def sql_flush( + self, style, tables, reset_sequences=False, allow_cascade=False + ): """ Override the base class method. Returns a list of SQL statements required to remove all data from the given database tables (without diff --git a/django_spanner/schema.py b/django_spanner/schema.py index b6c859c466..6d71f31673 100644 --- a/django_spanner/schema.py +++ b/django_spanner/schema.py @@ -13,6 +13,7 @@ class DatabaseSchemaEditor(BaseDatabaseSchemaEditor): The database abstraction layer that turns things like “create a model” or “delete a field” into SQL. """ + sql_create_table = ( "CREATE TABLE %(table)s (%(definition)s) PRIMARY KEY(%(primary_key)s)" ) diff --git a/docs/conf.py b/docs/conf.py index d26c0698e6..0de5312321 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,8 +18,7 @@ import sys import os - -from version import __version__ +import shlex # If extensions (or modules to document with autodoc) are in another directory, # add this directory to sys.path here. If the directory is relative to the @@ -30,10 +29,12 @@ # See also: https://github.com/docascode/sphinx-docfx-yaml/issues/85 sys.path.insert(0, os.path.abspath(".")) +__version__ = "" + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = "1.6.3" +needs_sphinx = "1.5.5" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -43,6 +44,7 @@ "sphinx.ext.autosummary", "sphinx.ext.intersphinx", "sphinx.ext.coverage", + "sphinx.ext.doctest", "sphinx.ext.napoleon", "sphinx.ext.todo", "sphinx.ext.viewcode", @@ -100,9 +102,6 @@ # directories to ignore when looking for source files. exclude_patterns = [ "_build", - "samples/AUTHORING_GUIDE.md", - "samples/CONTRIBUTING.md", - "samples/snippets/README.rst", ] # The reST default role (used for this markup: `text`) to use for all @@ -258,28 +257,28 @@ # -- Options for LaTeX output --------------------------------------------- latex_elements = { - # # The paper size ('letterpaper' or 'a4paper'). + # The paper size ('letterpaper' or 'a4paper'). # 'papersize': 'letterpaper', - # # The font size ('10pt', '11pt' or '12pt'). + # The font size ('10pt', '11pt' or '12pt'). # 'pointsize': '10pt', - # # Additional stuff for the LaTeX preamble. + # Additional stuff for the LaTeX preamble. # 'preamble': '', - # # Latex figure (float) alignment + # Latex figure (float) alignment # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source_start_file, target_name, title, author, # documentclass ["howto", "manual", or "own class"]). E.g., -# latex_documents = [ -# ( -# master_doc, -# "django-google-spanner.tex", -# u"Spanner Django Documentation", -# author, -# "manual", -# ) -# ] +latex_documents = [ + ( + master_doc, + "django-google-spanner.tex", + u"Spanner Django Documentation", + author, + "manual", + ) +] # The name of an image file (relative to this directory) # to place at the top of the title page. @@ -352,13 +351,13 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { - "python": ("http://python.readthedocs.org/en/latest/", None), - "google-auth": ("https://google-auth.readthedocs.io/en/stable", None), + "python": ("https://python.readthedocs.org/en/latest/", None), + "google-auth": ("https://googleapis.dev/python/google-auth/latest/", None), "google.api_core": ( "https://googleapis.dev/python/google-api-core/latest/", None, ), - "grpc": ("https://grpc.io/grpc/python/", None), + "grpc": ("https://grpc.github.io/grpc/python/", None), } diff --git a/noxfile.py b/noxfile.py index 2c1edbe573..8b4f76bbde 100644 --- a/noxfile.py +++ b/noxfile.py @@ -17,13 +17,18 @@ BLACK_VERSION = "black==19.10b0" BLACK_PATHS = [ "docs", + "django_spanner", "tests", "noxfile.py", "setup.py", ] +DEFAULT_PYTHON_VERSION = "3.8" +SYSTEM_TEST_PYTHON_VERSIONS = ["3.8"] +UNIT_TEST_PYTHON_VERSIONS = ["3.6", "3.7", "3.8"] -@nox.session(python="3.8") + +@nox.session(python=DEFAULT_PYTHON_VERSION) def lint(session): """Run linters. @@ -35,7 +40,7 @@ def lint(session): session.run("flake8", "django_spanner", "tests") -@nox.session(python="3.8") +@nox.session(python="3.6") def blacken(session): """Run black. @@ -49,7 +54,7 @@ def blacken(session): session.run("black", *BLACK_PATHS) -@nox.session(python="3.8") +@nox.session(python=DEFAULT_PYTHON_VERSION) def lint_setup_py(session): """Verify that setup.py is valid (including RST check).""" session.install("docutils", "pygments") @@ -70,23 +75,41 @@ def default(session): "py.test", "--quiet", "--cov=django_spanner", - "--cov=google.cloud", "--cov=tests.unit", "--cov-append", "--cov-config=.coveragerc", "--cov-report=", - "--cov-fail-under=60", + "--cov-fail-under=20", os.path.join("tests", "unit"), *session.posargs ) -@nox.session(python="3.8") +@nox.session(python=UNIT_TEST_PYTHON_VERSIONS) +def unit(session): + """Run the unit test suite.""" + default(session) + + +@nox.session(python=DEFAULT_PYTHON_VERSION) +def cover(session): + """Run the final coverage report. + + This outputs the coverage report aggregating coverage from the unit + test runs (not system test runs), and then erases coverage data. + """ + session.install("coverage", "pytest-cov") + session.run("coverage", "report", "--show-missing", "--fail-under=20") + + session.run("coverage", "erase") + + +@nox.session(python=DEFAULT_PYTHON_VERSION) def docs(session): """Build the docs for this library.""" - session.install("-e", ".") - session.install("sphinx<3.0.0", "alabaster", "recommonmark") + session.install("-e", ".[tracing]") + session.install("sphinx", "alabaster", "recommonmark") shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True) session.run( @@ -101,3 +124,40 @@ def docs(session): os.path.join("docs", ""), os.path.join("docs", "_build", "html", ""), ) + + +@nox.session(python=DEFAULT_PYTHON_VERSION) +def docfx(session): + """Build the docfx yaml files for this library.""" + + session.install("-e", ".[tracing]") + # sphinx-docfx-yaml supports up to sphinx version 1.5.5. + # https://github.com/docascode/sphinx-docfx-yaml/issues/97 + session.install( + "sphinx==1.5.5", "alabaster", "recommonmark", "sphinx-docfx-yaml" + ) + + shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True) + session.run( + "sphinx-build", + "-T", # show full traceback on exception + "-N", # no colors + "-D", + ( + "extensions=sphinx.ext.autodoc," + "sphinx.ext.autosummary," + "docfx_yaml.extension," + "sphinx.ext.intersphinx," + "sphinx.ext.coverage," + "sphinx.ext.napoleon," + "sphinx.ext.todo," + "sphinx.ext.viewcode," + "recommonmark" + ), + "-b", + "html", + "-d", + os.path.join("docs", "_build", "doctrees", ""), + os.path.join("docs", ""), + os.path.join("docs", "_build", "html", ""), + ) diff --git a/tests/unit/django_spanner/test_base.py b/tests/unit/django_spanner/test_base.py index c45cd1380d..32d965b9d1 100644 --- a/tests/unit/django_spanner/test_base.py +++ b/tests/unit/django_spanner/test_base.py @@ -6,15 +6,18 @@ import sys import unittest +import os from mock_import import mock_import from unittest import mock @mock_import() -@unittest.skipIf(sys.version_info < (3, 6), reason="Skipping Python 3.5") +@unittest.skipIf( + sys.version_info < (3, 6), reason="Skipping Python versions <= 3.5" +) class TestBase(unittest.TestCase): - PROJECT = "project" + PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"] INSTANCE_ID = "instance_id" DATABASE_ID = "database_id" USER_AGENT = "django_spanner/2.2.0a1" @@ -64,10 +67,10 @@ def test_get_connection_params(self): def test_get_new_connection(self): db_wrapper = self._make_one(self.settings_dict) db_wrapper.Database = mock_database = mock.MagicMock() - mock_database.connect = mock_connect = mock.MagicMock() + mock_database.connect = mock_connection = mock.MagicMock() conn_params = {"test_param": "dummy"} db_wrapper.get_new_connection(conn_params) - mock_connect.assert_called_once_with(**conn_params) + mock_connection.assert_called_once_with(**conn_params) def test_init_connection_state(self): db_wrapper = self._make_one(self.settings_dict) @@ -106,3 +109,10 @@ def test_is_usable(self): mock_connection.cursor = mock.MagicMock(side_effect=Error) self.assertFalse(db_wrapper.is_usable()) + + def test__start_transaction_under_autocommit(self): + db_wrapper = self._make_one(self.settings_dict) + db_wrapper.connection = mock_connection = mock.MagicMock() + mock_connection.cursor = mock_cursor = mock.MagicMock() + db_wrapper._start_transaction_under_autocommit() + mock_cursor.assert_called_once_with() diff --git a/tests/unit/django_spanner/test_client.py b/tests/unit/django_spanner/test_client.py new file mode 100644 index 0000000000..fd02434b04 --- /dev/null +++ b/tests/unit/django_spanner/test_client.py @@ -0,0 +1,44 @@ +# Copyright 2020 Google LLC +# +# Use of this source code is governed by a BSD-style +# license that can be found in the LICENSE file or at +# https://developers.google.com/open-source/licenses/bsd + +import sys +import unittest +import os + + +@unittest.skipIf( + sys.version_info < (3, 6), reason="Skipping Python versions <= 3.5" +) +class TestClient(unittest.TestCase): + PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"] + INSTANCE_ID = "instance_id" + DATABASE_ID = "database_id" + USER_AGENT = "django_spanner/2.2.0a1" + OPTIONS = {"option": "dummy"} + + settings_dict = { + "PROJECT": PROJECT, + "INSTANCE": INSTANCE_ID, + "NAME": DATABASE_ID, + "user_agent": USER_AGENT, + "OPTIONS": OPTIONS, + } + + def _get_target_class(self): + from django_spanner.client import DatabaseClient + + return DatabaseClient + + def _make_one(self, *args, **kwargs): + return self._get_target_class()(*args, **kwargs) + + def test_runshell(self): + from google.cloud.spanner_dbapi.exceptions import NotSupportedError + + db_wrapper = self._make_one(self.settings_dict) + + with self.assertRaises(NotSupportedError): + db_wrapper.runshell(parameters=self.settings_dict) From 2bc42b046a307598d7e98ab3d548dd5b9d98df8c Mon Sep 17 00:00:00 2001 From: Vikash Singh <3116482+vi3k6i5@users.noreply.github.com> Date: Tue, 6 Apr 2021 09:43:39 +0530 Subject: [PATCH 2/3] feat: updated nox file for docs and docfx and added unit tests for client --- .gitignore | 3 +- docs/conf.py | 40 +++++++++-------- noxfile.py | 56 ++++++++++++++++++++++++ tests/unit/django_spanner/test_base.py | 18 ++++++-- tests/unit/django_spanner/test_client.py | 44 +++++++++++++++++++ 5 files changed, 137 insertions(+), 24 deletions(-) create mode 100644 tests/unit/django_spanner/test_client.py diff --git a/.gitignore b/.gitignore index efe8469b33..4a39372126 100644 --- a/.gitignore +++ b/.gitignore @@ -12,7 +12,8 @@ bin MANIFEST django_tests __pycache__ - +# The directory into which Django has been cloned to run the test suite. +django_tests_dir # Unit test / coverage reports .coverage .nox diff --git a/docs/conf.py b/docs/conf.py index 1cffc0625d..0de5312321 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,8 +18,7 @@ import sys import os - -from version import __version__ +import shlex # If extensions (or modules to document with autodoc) are in another directory, # add this directory to sys.path here. If the directory is relative to the @@ -30,10 +29,12 @@ # See also: https://github.com/docascode/sphinx-docfx-yaml/issues/85 sys.path.insert(0, os.path.abspath(".")) +__version__ = "" + # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = "1.6.3" +needs_sphinx = "1.5.5" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -43,6 +44,7 @@ "sphinx.ext.autosummary", "sphinx.ext.intersphinx", "sphinx.ext.coverage", + "sphinx.ext.doctest", "sphinx.ext.napoleon", "sphinx.ext.todo", "sphinx.ext.viewcode", @@ -255,28 +257,28 @@ # -- Options for LaTeX output --------------------------------------------- latex_elements = { - # # The paper size ('letterpaper' or 'a4paper'). + # The paper size ('letterpaper' or 'a4paper'). # 'papersize': 'letterpaper', - # # The font size ('10pt', '11pt' or '12pt'). + # The font size ('10pt', '11pt' or '12pt'). # 'pointsize': '10pt', - # # Additional stuff for the LaTeX preamble. + # Additional stuff for the LaTeX preamble. # 'preamble': '', - # # Latex figure (float) alignment + # Latex figure (float) alignment # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source_start_file, target_name, title, author, # documentclass ["howto", "manual", or "own class"]). E.g., -# latex_documents = [ -# ( -# master_doc, -# "django-google-spanner.tex", -# u"Spanner Django Documentation", -# author, -# "manual", -# ) -# ] +latex_documents = [ + ( + master_doc, + "django-google-spanner.tex", + u"Spanner Django Documentation", + author, + "manual", + ) +] # The name of an image file (relative to this directory) # to place at the top of the title page. @@ -349,13 +351,13 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { - "python": ("http://python.readthedocs.org/en/latest/", None), - "google-auth": ("https://google-auth.readthedocs.io/en/stable", None), + "python": ("https://python.readthedocs.org/en/latest/", None), + "google-auth": ("https://googleapis.dev/python/google-auth/latest/", None), "google.api_core": ( "https://googleapis.dev/python/google-api-core/latest/", None, ), - "grpc": ("https://grpc.io/grpc/python/", None), + "grpc": ("https://grpc.github.io/grpc/python/", None), } diff --git a/noxfile.py b/noxfile.py index 7bea0b8dda..8b4f76bbde 100644 --- a/noxfile.py +++ b/noxfile.py @@ -85,6 +85,25 @@ def default(session): ) +@nox.session(python=UNIT_TEST_PYTHON_VERSIONS) +def unit(session): + """Run the unit test suite.""" + default(session) + + +@nox.session(python=DEFAULT_PYTHON_VERSION) +def cover(session): + """Run the final coverage report. + + This outputs the coverage report aggregating coverage from the unit + test runs (not system test runs), and then erases coverage data. + """ + session.install("coverage", "pytest-cov") + session.run("coverage", "report", "--show-missing", "--fail-under=20") + + session.run("coverage", "erase") + + @nox.session(python=DEFAULT_PYTHON_VERSION) def docs(session): """Build the docs for this library.""" @@ -105,3 +124,40 @@ def docs(session): os.path.join("docs", ""), os.path.join("docs", "_build", "html", ""), ) + + +@nox.session(python=DEFAULT_PYTHON_VERSION) +def docfx(session): + """Build the docfx yaml files for this library.""" + + session.install("-e", ".[tracing]") + # sphinx-docfx-yaml supports up to sphinx version 1.5.5. + # https://github.com/docascode/sphinx-docfx-yaml/issues/97 + session.install( + "sphinx==1.5.5", "alabaster", "recommonmark", "sphinx-docfx-yaml" + ) + + shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True) + session.run( + "sphinx-build", + "-T", # show full traceback on exception + "-N", # no colors + "-D", + ( + "extensions=sphinx.ext.autodoc," + "sphinx.ext.autosummary," + "docfx_yaml.extension," + "sphinx.ext.intersphinx," + "sphinx.ext.coverage," + "sphinx.ext.napoleon," + "sphinx.ext.todo," + "sphinx.ext.viewcode," + "recommonmark" + ), + "-b", + "html", + "-d", + os.path.join("docs", "_build", "doctrees", ""), + os.path.join("docs", ""), + os.path.join("docs", "_build", "html", ""), + ) diff --git a/tests/unit/django_spanner/test_base.py b/tests/unit/django_spanner/test_base.py index c45cd1380d..32d965b9d1 100644 --- a/tests/unit/django_spanner/test_base.py +++ b/tests/unit/django_spanner/test_base.py @@ -6,15 +6,18 @@ import sys import unittest +import os from mock_import import mock_import from unittest import mock @mock_import() -@unittest.skipIf(sys.version_info < (3, 6), reason="Skipping Python 3.5") +@unittest.skipIf( + sys.version_info < (3, 6), reason="Skipping Python versions <= 3.5" +) class TestBase(unittest.TestCase): - PROJECT = "project" + PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"] INSTANCE_ID = "instance_id" DATABASE_ID = "database_id" USER_AGENT = "django_spanner/2.2.0a1" @@ -64,10 +67,10 @@ def test_get_connection_params(self): def test_get_new_connection(self): db_wrapper = self._make_one(self.settings_dict) db_wrapper.Database = mock_database = mock.MagicMock() - mock_database.connect = mock_connect = mock.MagicMock() + mock_database.connect = mock_connection = mock.MagicMock() conn_params = {"test_param": "dummy"} db_wrapper.get_new_connection(conn_params) - mock_connect.assert_called_once_with(**conn_params) + mock_connection.assert_called_once_with(**conn_params) def test_init_connection_state(self): db_wrapper = self._make_one(self.settings_dict) @@ -106,3 +109,10 @@ def test_is_usable(self): mock_connection.cursor = mock.MagicMock(side_effect=Error) self.assertFalse(db_wrapper.is_usable()) + + def test__start_transaction_under_autocommit(self): + db_wrapper = self._make_one(self.settings_dict) + db_wrapper.connection = mock_connection = mock.MagicMock() + mock_connection.cursor = mock_cursor = mock.MagicMock() + db_wrapper._start_transaction_under_autocommit() + mock_cursor.assert_called_once_with() diff --git a/tests/unit/django_spanner/test_client.py b/tests/unit/django_spanner/test_client.py new file mode 100644 index 0000000000..fd02434b04 --- /dev/null +++ b/tests/unit/django_spanner/test_client.py @@ -0,0 +1,44 @@ +# Copyright 2020 Google LLC +# +# Use of this source code is governed by a BSD-style +# license that can be found in the LICENSE file or at +# https://developers.google.com/open-source/licenses/bsd + +import sys +import unittest +import os + + +@unittest.skipIf( + sys.version_info < (3, 6), reason="Skipping Python versions <= 3.5" +) +class TestClient(unittest.TestCase): + PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"] + INSTANCE_ID = "instance_id" + DATABASE_ID = "database_id" + USER_AGENT = "django_spanner/2.2.0a1" + OPTIONS = {"option": "dummy"} + + settings_dict = { + "PROJECT": PROJECT, + "INSTANCE": INSTANCE_ID, + "NAME": DATABASE_ID, + "user_agent": USER_AGENT, + "OPTIONS": OPTIONS, + } + + def _get_target_class(self): + from django_spanner.client import DatabaseClient + + return DatabaseClient + + def _make_one(self, *args, **kwargs): + return self._get_target_class()(*args, **kwargs) + + def test_runshell(self): + from google.cloud.spanner_dbapi.exceptions import NotSupportedError + + db_wrapper = self._make_one(self.settings_dict) + + with self.assertRaises(NotSupportedError): + db_wrapper.runshell(parameters=self.settings_dict) From cd3951c350b15981a0c254883cad277dfed9fb35 Mon Sep 17 00:00:00 2001 From: Vikash Singh <3116482+vi3k6i5@users.noreply.github.com> Date: Wed, 7 Apr 2021 11:53:27 +0530 Subject: [PATCH 3/3] feat: added docfx build in nox file --- docs/_static/custom.css | 9 +++++++++ docs/api-reference.rst | 5 ++++- docs/conf.py | 2 +- docs/index.rst | 8 ++++++++ docs/schema-api.rst | 8 ++++++++ docs/schema-usage.rst | 4 ++++ noxfile.py | 17 ++++++++++------- 7 files changed, 44 insertions(+), 9 deletions(-) create mode 100644 docs/_static/custom.css create mode 100644 docs/schema-api.rst create mode 100644 docs/schema-usage.rst diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000000..bcd37bbd3c --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,9 @@ +div#python2-eol { + border-color: red; + border-width: medium; +} + +/* Ensure minimum width for 'Parameters' / 'Returns' column */ +dl.field-list > dt { + min-width: 100px +} diff --git a/docs/api-reference.rst b/docs/api-reference.rst index 847846a55e..c201e01e10 100644 --- a/docs/api-reference.rst +++ b/docs/api-reference.rst @@ -3,4 +3,7 @@ API Reference The following classes and methods constitute the Django Spanner API. -[this page is under construction] +.. toctree:: + :maxdepth: 1 + + schema-api diff --git a/docs/conf.py b/docs/conf.py index 0de5312321..301aa06e84 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -173,7 +173,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ["_static"] +html_static_path = ["_static"] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/index.rst b/docs/index.rst index 5e9fef5773..ca432559cf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,13 @@ .. include:: README.rst +Usage Documentation +------------------- +.. toctree:: + :maxdepth: 1 + :titlesonly: + + schema-usage + API Documentation ----------------- .. toctree:: diff --git a/docs/schema-api.rst b/docs/schema-api.rst new file mode 100644 index 0000000000..c0118ed24a --- /dev/null +++ b/docs/schema-api.rst @@ -0,0 +1,8 @@ +Schema API +===================== + +.. automodule:: django_spanner.schema + :members: + :inherited-members: + + diff --git a/docs/schema-usage.rst b/docs/schema-usage.rst new file mode 100644 index 0000000000..451813b498 --- /dev/null +++ b/docs/schema-usage.rst @@ -0,0 +1,4 @@ +Schema +#################################### + +[this page is under construction] diff --git a/noxfile.py b/noxfile.py index 8b4f76bbde..d2d3e1ebf3 100644 --- a/noxfile.py +++ b/noxfile.py @@ -79,7 +79,7 @@ def default(session): "--cov-append", "--cov-config=.coveragerc", "--cov-report=", - "--cov-fail-under=20", + "--cov-fail-under=25", os.path.join("tests", "unit"), *session.posargs ) @@ -109,12 +109,13 @@ def docs(session): """Build the docs for this library.""" session.install("-e", ".[tracing]") - session.install("sphinx", "alabaster", "recommonmark") + session.install("sphinx", "alabaster", "recommonmark", "django==2.2") shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True) + # Warnings as errors is disabled for `sphinx-build` because django module + # has warnings. session.run( "sphinx-build", - "-W", # warnings as errors "-T", # show full traceback on exception "-N", # no colors "-b", @@ -130,11 +131,13 @@ def docs(session): def docfx(session): """Build the docfx yaml files for this library.""" - session.install("-e", ".[tracing]") - # sphinx-docfx-yaml supports up to sphinx version 1.5.5. - # https://github.com/docascode/sphinx-docfx-yaml/issues/97 + session.install("-e", ".") session.install( - "sphinx==1.5.5", "alabaster", "recommonmark", "sphinx-docfx-yaml" + "sphinx", + "alabaster", + "recommonmark", + "sphinx-docfx-yaml", + "django==2.2", ) shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)