diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py index 687eafc..56f0702 100644 --- a/api-ref/source/conf.py +++ b/api-ref/source/conf.py @@ -18,7 +18,7 @@ import os import sys extensions = [ - 'otcdocstheme' + 'otcdocstheme', ] otcdocs_auto_name = False diff --git a/doc/requirements.txt b/doc/requirements.txt index ea68e86..ea0c4de 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,4 +1,7 @@ sphinx>=2.0.0,!=2.1.0 # BSD otcdocstheme # Apache-2.0 # releasenotes -reno>=3.1.0 # Apache-2.0 \ No newline at end of file +reno>=3.1.0 # Apache-2.0 + +otc-sphinx-directives>=0.1.0 +git+https://gitea.eco.tsi-dev.otc-service.com/infra/otc-metadata.git#egg=otc_metadata \ No newline at end of file diff --git a/doc/source/_static/placeholder b/doc/source/_static/placeholder new file mode 100644 index 0000000..e69de29 diff --git a/doc/source/conf.py b/doc/source/conf.py index 6f07e52..e9a4a1e 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,75 +1,102 @@ -# -*- coding: utf-8 -*- -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -# implied. -# See the License for the specific language governing permissions and -# limitations under the License. +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# !!! +# This file is generated out of template in doc-exports repository. +# Beware overwriting it locally. import os import sys -sys.path.insert(0, os.path.abspath('../..')) +extensions = [ + 'otcdocstheme', + 'otc_sphinx_directives' +] + +otcdocs_auto_name = False +otcdocs_auto_version = False + +project = 'GaussDB (for MySQL)' +otcdocs_repo_name = 'docs/gaussdb-mysql' +# Those variables are required for edit/bug links +otcdocs_git_fqdn = 'gitea.eco.tsi-dev.otc-service.com' +otcdocs_git_type = 'gitea' + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) + # -- General configuration ---------------------------------------------------- +# https://docutils.sourceforge.io/docs/user/smartquotes.html - it does not +# what it is expected +smartquotes = False # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - 'sphinx.ext.autodoc', - 'otcdocstheme', -] - -# autodoc generation is a bit aggressive and a nuisance when doing heavy -# text edit cycles. -# execute "export SPHINX_DEBUG=1" in your terminal to disable # The suffix of source filenames. source_suffix = '.rst' +# The encoding of source files. +# +source_encoding = 'utf-8' + # The master toctree document. master_doc = 'index' # General information about the project. -project = 'gaussdb-mysql' -copyright = '2022, Open Telekom Cloud Developers' +copyright = u'2022-present, Open Telekom Cloud' -# If true, '()' will be appended to :func: etc. cross-reference text. -add_function_parentheses = True +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +language = 'en' -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -add_module_names = True - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'native' +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. Major themes that come with # Sphinx are currently 'default' and 'sphinxdoc'. # html_theme_path = ["."] -# html_theme = '_theme' -# html_static_path = ['static'] html_theme = 'otcdocs' -# Output file base name for HTML help builder. -htmlhelp_basename = '%sdoc' % project +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +html_theme_options = { + "disable_search": True, + "site_name": "Internal Documentation Portal", + "logo_url": "https://docs-int.otc-service.com", +} -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto/manual]). -latex_documents = [ - ('index', - '%s.tex' % project, - '%s Documentation' % project, - 'Open Telekom Cloud Developers', 'manual'), -] +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". -# Example configuration for intersphinx: refer to the Python standard library. -#intersphinx_mapping = {'http://docs.python.org/': None} +html_title = "GaussDB (for MySQL) - Service Based View" + + +# 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'] + +# Do not include sources into the rendered results +html_copy_source = False + +# -- Options for PDF output -------------------------------------------------- +latex_documents = [] diff --git a/doc/source/index.rst b/doc/source/index.rst index 44ca61e..b744283 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,3 +1,13 @@ -============================================= -Welcome to the documentation of gaussdb-mysql -============================================= +GaussDB (for MySQL) +=================== + +GaussDB(for MySQL) is the latest generation enterprise-class distributed database. It is fully compatible with MySQL and provides high scalability and massive storage capacity. It uses a decoupled compute and storage architecture and supports up to 128 TB of storage. With GaussDB(for MySQL), there is no need to deal with sharding, and no need to worry about data loss. It combines the performance and availability of commercial databases with the cost-effectiveness of open source databases. + +.. directive_wrapper:: + :class: container-sbv + + .. service_card:: + :service_type: gaussdb_mysql + :umn: This document describes basic concepts, functions, key terms, and FAQs of GaussDB(for MySQL) and provides instructions for applying for and using GaussDB(for MySQL). + :api-ref: This document describes application programming interfaces (APIs) of GaussDB(for MySQL) and provides API parameter description and example values. + \ No newline at end of file diff --git a/tox.ini b/tox.ini index 0511308..057c677 100644 --- a/tox.ini +++ b/tox.ini @@ -29,7 +29,11 @@ allowlist_externals = mkdir cp sh + rm + sphinx-build commands = + rm -rf doc/build/html doc/build/doctrees + sphinx-build -a -E -W -d doc/build/doctrees -b html doc/source doc/build/html {[testenv:api-ref]commands} {[testenv:json-api-ref]commands} {[testenv:umn]commands} @@ -138,3 +142,8 @@ commands = mkdir -p doc/build/pdf cp umn/build/pdf/gaussdb_mysql-umn.pdf doc/build/pdf/ + + +[doc8] +ignore = D001 +extensions = .rst, .yaml \ No newline at end of file diff --git a/umn/source/conf.py b/umn/source/conf.py index eb4c8ce..e1e64d6 100644 --- a/umn/source/conf.py +++ b/umn/source/conf.py @@ -18,7 +18,7 @@ import os import sys extensions = [ - 'otcdocstheme' + 'otcdocstheme', ] otcdocs_auto_name = False