docs: Add sample configuration into doc

Change-Id: I364938b4b1547bde0633a9c33af9fd0502b506a7

doc/source/admin/index.rst

@@ -1,6 +1,6 @@
-===========
+====================
-Admin Guide
+Administration Guide
-===========
+====================
 
 .. toctree::
    :maxdepth: 1

doc/source/cli/index.rst

@@ -1,19 +0,0 @@
-..
-      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.
-
-
-Command Line Interface
-----------------------
-
-.. toctree::
-    :maxdepth: 1

doc/source/conf.py

@@ -10,11 +10,11 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 #
-# skyline-apiserver documentation build configuration file, created by
+# Skyline APIServer documentation build configuration file, created by
-# sphinx-quickstart on Fri July 29 11:11:50 2022.
+# sphinx-quickstart on Thu Aug 1 14:22:36 2022.
 #
-# This file is execfile()d with the current directory set
+# This file is execfile()d with the current directory set to its
-# to its containing dir.
+# containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
@@ -22,8 +22,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import sys
 
 # 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
@@ -34,10 +34,12 @@ sys.path.insert(0, os.path.abspath('./'))
 
 # -- General configuration ----------------------------------------------------
 
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+
 # 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',
               'sphinx.ext.coverage',
               'sphinx.ext.ifconfig',
@@ -47,20 +49,32 @@ extensions = ['sphinx.ext.autodoc',
 
 # openstackdocstheme options
 openstackdocs_repo_name = 'openstack/skyline-apiserver'
-openstackdocs_pdf_link = True
 openstackdocs_bug_project = 'skyline-apiserver'
 openstackdocs_bug_tag = 'docs'
+openstackdocs_pdf_link = True
 
-todo_include_todos = True
+# Set aliases for extlinks
+# - bug - [:bug:`12345`]
+# - blueprint - [:blueprint:`xxx-yyy`]
+extlinks = {
+    'opendev-repo': (
+        'https://opendev.org/%s',
+        '',
+    ),
+    'launchpad': (
+        'https://bugs.launchpad.net/%s',
+        'launchpad ',
+    ),
+}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = []
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 # The encoding of source files.
-# source_encoding = 'utf-8'
+# source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
@@ -68,7 +82,6 @@ master_doc = 'index'
 # General information about the project.
 copyright = '2022, Skyline APIServer developers'
 
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 # language = None
@@ -79,15 +92,12 @@ copyright = '2022, Skyline APIServer developers'
 # Else, today_fmt is used as the format for a strftime call.
 # today_fmt = '%B %d, %Y'
 
-# List of documents that shouldn't be included in the build.
+# List of patterns, relative to source directory, that match files and
-unused_docs = []
+# directories to ignore when looking for source files.
+exclude_patterns = ['**/#*', '**~', '**/#*#']
 
-# List of directories, relative to source directory, that shouldn't be searched
+# The reST default role (used for this markup: `text`)
-# for source files.
+# to use for all documents.
-exclude_trees = []
-
-# The reST default role (used for this markup: `text`) to use
-# for all documents.
 # default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -95,7 +105,7 @@ exclude_trees = []
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-add_module_names = False
+# add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
@@ -105,33 +115,29 @@ show_authors = False
 pygments_style = 'native'
 
 # A list of ignored prefixes for module index sorting.
-modindex_common_prefix = ['skyline-apiserver.']
+modindex_common_prefix = ['skyline_apiserver.']
 
-# -- Options for man page output ----------------------------------------------
+primary_domain = 'py'
+nitpicky = False
 
-# Grouping the document tree for man pages.
-# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
-
-# man_pages = [
-#     ('cli/manila-manage', 'manila-manage', u'Cloud controller fabric',
-#      [u'OpenStack'], 1),
-#     ('cli/manila-status', 'manila-status', u'Cloud controller fabric',
-#      [u'OpenStack'], 1),
-# ]
 
 # -- Options for HTML output --------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
+# html_theme_path = ['.']
 html_theme = 'openstackdocs'
 
 # 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 = {
-    "show_other_versions": "True",
+    "show_other_versions": "True"
 }
 
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 # html_title = None
@@ -151,7 +157,7 @@ html_theme_options = {
 # 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 = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -169,7 +175,7 @@ html_theme_options = {
 # html_additional_pages = {}
 
 # If false, no module index is generated.
-# html_use_modindex = True
+# html_domain_indices = True
 
 # If false, no index is generated.
 # html_use_index = True
@@ -180,26 +186,25 @@ html_theme_options = {
 # If true, links to the reST sources are added to the pages.
 # html_show_sourcelink = True
 
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 # html_use_opensearch = ''
 
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = ''
+# html_file_suffix = None
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'SkylineAPIServerdoc'
 
-
 # -- Options for LaTeX output -------------------------------------------------
 
-# The paper size ('letter' or 'a4').
-# latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-# latex_font_size = '10pt'
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass
 # [howto/manual]).
@@ -216,20 +221,98 @@ latex_documents = [
 # not chapters.
 # latex_use_parts = False
 
-# Additional stuff for the LaTeX preamble.
+# If true, show page references after internal links.
-# latex_preamble = ''
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+# latex_show_urls = False
 
 # Documents to append as an appendix to all manuals.
 # latex_appendices = []
 
 # If false, no module index is generated.
-# latex_use_modindex = True
-
 latex_domain_indices = False
 
 latex_elements = {
     'makeindex': '',
     'printindex': '',
     'preamble': r'\setcounter{tocdepth}{3}',
-    'maxlistdepth': 10,
 }
+
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
+# -- Options for manual page output -------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'skyline_apiserver', 'Skyline APIServer Documentation',
+     ['OpenStack'], 1)
+]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    ('index', 'Skyline APIServer', 'Skyline APIServer Documentation', 'OpenStack',
+     'Skyline APIServer', 'One line description of project.', 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+# texinfo_show_urls = 'footnote'
+
+
+# -- Options for Epub output --------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = 'Skyline APIServer'
+epub_author = 'OpenStack'
+epub_publisher = 'OpenStack'
+epub_copyright = '2022, Skyline APIServer developers'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+# epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+# epub_scheme = ''
+
+# The unique identifier of the text. This can be an ISBN number
+# or the project homepage.
+# epub_identifier = ''
+
+# A unique identification for the text.
+# epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+# epub_cover = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+# epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+# epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+# epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+# epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+# epub_tocdup = True

doc/source/configuration/index.rst

@@ -1,6 +1,8 @@
-=============
+===================
-Configuration
+Configuration Guide
-=============
+===================
 
 .. toctree::
    :maxdepth: 1
+
+   settings

doc/source/configuration/settings.rst

@@ -0,0 +1,90 @@
+.. _configuration-settings:
+
+==================
+Settings Reference
+==================
+
+Skyline APIServer use ``tox -e genconfig`` to generate a sample configuration
+file ``skyline.yaml.sample`` in ``etc`` directory.
+
+.. code-block:: yaml
+
+    default:
+      access_token_expire: 3600
+      access_token_renew: 1800
+      cors_allow_origins: []
+      database_url: sqlite:////tmp/skyline.db
+      debug: false
+      log_dir: ./log
+      prometheus_basic_auth_password: ''
+      prometheus_basic_auth_user: ''
+      prometheus_enable_basic_auth: false
+      prometheus_endpoint: http://localhost:9091
+      secret_key: aCtmgbcUqYUy_HNVg5BDXCaeJgJQzHJXwqbXr0Nmb2o
+      session_name: session
+    openstack:
+      base_domains:
+      - heat_user_domain
+      default_region: RegionOne
+      extension_mapping:
+        floating-ip-port-forwarding: neutron_port_forwarding
+        fwaas_v2: neutron_firewall
+        qos: neutron_qos
+        vpnaas: neutron_vpn
+      interface_type: public
+      keystone_url: http://localhost:5000/v3/
+      nginx_prefix: /api/openstack
+      reclaim_instance_interval: 604800
+      service_mapping:
+        baremetal: ironic
+        compute: nova
+        container: zun
+        container-infra: magnum
+        database: trove
+        identity: keystone
+        image: glance
+        key-manager: barbican
+        load-balancer: octavia
+        network: neutron
+        object-store: swift
+        orchestration: heat
+        placement: placement
+        sharev2: manilav2
+        volumev3: cinder
+      system_admin_roles:
+      - admin
+      - system_admin
+      system_project: service
+      system_project_domain: Default
+      system_reader_roles:
+      - system_reader
+      system_user_domain: Default
+      system_user_name: skyline
+      system_user_password: ''
+    setting:
+      base_settings:
+      - flavor_families
+      - gpu_models
+      - usb_models
+      flavor_families:
+      - architecture: x86_architecture
+        categories:
+        - name: general_purpose
+          properties: []
+        - name: compute_optimized
+          properties: []
+        - name: memory_optimized
+          properties: []
+        - name: high_clock_speed
+          properties: []
+      - architecture: heterogeneous_computing
+        categories:
+        - name: compute_optimized_type_with_gpu
+          properties: []
+        - name: visualization_compute_optimized_type_with_gpu
+          properties: []
+      gpu_models:
+      - nvidia_t4
+      usb_models:
+      - usb_c
+

doc/source/contributor/index.rst

@@ -1,34 +1,6 @@
-..
-      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.
-
-
-Contributor/Developer Guide
 ===========================
-
+ Contributor Documentation
-In this section you will find information helpful for contributing to skyline-apiserver.
+===========================
-
-
-Basic Information
------------------
 
 .. toctree::
    :maxdepth: 1
-
-.. only:: html
-
-   Indices and tables
-   ------------------
-
-   * :ref:`genindex`
-   * :ref:`search`
-

doc/source/glossary.rst

@@ -0,0 +1,5 @@
+.. _glossary:
+
+========
+Glossary
+========

doc/source/index.rst

@@ -11,84 +11,52 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+=====================================================
+Skyline APIServer (API of OpenStack Modern Dashboard)
+=====================================================
 
-============================================================
+Introduction
-OpenStack Modern Dashboard (Skyline APIServer) documentation
+============
-============================================================
 
-What is Skyline APIServer?
+`Skyline APIServer <https://github.com/openstack/skyline-apiserver>`_ is one
---------------------------
+part of OpenStack Modern Dashboard, which provides RESTful APIs to
+`Skyline Console <https://github.com/openstack/skyline-console>`_.
 
-Skyline APIServer is one part of the OpenStack Modern Dashboard for providing
+Using Skyline APIServer
-restful api.
+=======================
 
-For end users
+How to use Skyline APIServer in your own projects.
--------------
-
-As an end user, we don't suggest you to use this Skyline APIServer directly.
-Instead, you should use Skyline Dashboard(With Skyline Console).
-
-For operators
--------------
-
-Installing Skyline APIServer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    install/index
-
+   configuration/index
-Administrating Skyline APIServer
+   User Documentation <user/index>
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Contents:
-
-.. toctree::
-   :maxdepth: 1
-
    admin/index
 
-Reference
+Contributor Docs
-~~~~~~~~~
+================
-
-Contents:
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
-
-   configuration/index
-   cli/index
-
-Additional resources
-~~~~~~~~~~~~~~~~~~~~
-
-
-For contributors
-----------------
-
-
-.. toctree::
-   :maxdepth: 1
 
    contributor/index
 
-Additional reference
+Release Notes
-~~~~~~~~~~~~~~~~~~~~
+=============
 
-Contents:
+See https://docs.openstack.org/releasenotes/skyline-apiserver
+
+Information
+===========
 
 .. toctree::
    :maxdepth: 1
 
-   reference/index
+   glossary
 
 .. only:: html
 
-   Additional reference
-   ~~~~~~~~~~~~~~~~~~~~
-
-   Contents:
-
    * :ref:`genindex`
-
+   * :ref:`modindex`

doc/source/install/index.rst

@@ -1,6 +1,23 @@
-=====================
+==================
-Installation Tutorial
+Installation Guide
-=====================
+==================
+
+This section describes how to install and configure the dashboard on the controller node.
+
+System Requirements
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+Installing from Packages
+========================
+
+.. toctree::
+   :maxdepth: 1
+
+Installing from Source
+======================
 
 .. toctree::
    :maxdepth: 1

doc/source/reference/index.rst

@@ -1,19 +0,0 @@
-..
-      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.
-
-
-Reference
----------
-
-.. toctree::
-    :maxdepth: 1

doc/source/user/index.rst

@@ -0,0 +1,6 @@
+========================================
+User Documentation
+========================================
+
+.. toctree::
+   :maxdepth: 1