build structure of read-the-docs

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

doc/source/api.rst

@@ -0,0 +1,7 @@
+.. _api_reference:
+
+=============
+API reference
+=============
+
+

doc/source/conf.py

@@ -0,0 +1,124 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'sphinx_panels',
+    'IPython.sphinxext.ipython_directive',
+    'IPython.sphinxext.ipython_console_highlighting',
+    'matplotlib.sphinxext.plot_directive',
+    'numpydoc',
+    'sphinx_copybutton',
+    'myst_nb',
+]
+
+templates_path = ['_templates']
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+exclude_patterns = []
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# General information about the project.
+project = 'AMS'
+copyright = '2023, Jinning Wang'
+author = 'Jinning Wang'
+release = '0.4'
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'pydata_sphinx_theme'
+
+# 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 = {
+    "use_edit_page_button": True,
+}
+
+html_context = {
+    "github_url": "https://github.com",
+    "github_user": "jinningwang",
+    "github_repo": "ams",
+    "github_version": "master",
+    "doc_path": "docs/source",
+}
+
+# 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']
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'ams'
+
+# -- 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 = [
+#     (master_doc, 'andes', 'ANDES Manual',
+#      author, 'andes', 'Python Software for Symbolic Power System Modeling and Numerical Analysis',
+#      'Miscellaneous'),
+# ]
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'numpy': ('https://docs.scipy.org/doc/numpy/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
+    'matplotlib': ('https://matplotlib.org', None),
+}
+
+# Favorite icon
+html_favicon = 'images/curent.ico'
+
+# Disable smartquotes to display double dashes correctly
+smartquotes = False
+
+# import and execute model reference generation script
+exec(open("genroutineref.py").read())
+
+# sphinx-panels shouldn't add bootstrap css since the pydata-sphinx-theme
+# already loads it
+panels_add_bootstrap_css = False

doc/source/examples/index.rst

@@ -0,0 +1,4 @@
+.. _scripting_examples:
+
+Examples
+========

doc/source/genroutineref.py

@@ -0,0 +1,3 @@
+"""
+This file is used to generate reStructuredText tables for Routine references.
+"""

doc/source/getting_started/index.rst

@@ -0,0 +1,21 @@
+
+.. raw:: html
+
+   <embed>
+   <h1 style="letter-spacing: 0.4em; font-size: 2.5em !important;
+   margin-bottom: 0; padding-bottom: 0"> AMS </h1>
+
+   <p style="color: #00746F; font-variant: small-caps; font-weight: bold;
+   margin-bottom: 2em">
+   Python Library for Power System Dispatch Modeling and Dispatch-Dynamic Co-Simulation</p>
+   </embed>
+
+.. _getting-started:
+
+===============
+Getting started
+===============
+
+.. toctree::
+    :maxdepth: 3
+    :hidden:

doc/source/index.rst

@@ -0,0 +1,106 @@
+.. AMS documentation master file, created by
+   sphinx-quickstart on Thu Jan 26 15:32:32 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+==================
+AMS documentation
+==================
+**Useful Links**: `Source Repository`_ | `Report Issues`_ | `Q&A`_ 
+
+.. _`Source Repository`: https://github.com/jinningwang/ams
+.. _`Report Issues`: https://github.com/jinningwang/ams/issues
+.. _`Q&A`: https://github.com/jinningwang/ams/discussions
+.. _`LTB Repository`: https://github.com/CURENT/ltb2
+
+AMS is still under DEVELOPMENT, stay tuned!
+
+AMS is an open-source packages for dispatch modeling and co-simulation with dynanic.
+
+AMS is the dispatch simulation engine for the CURENT Largescale Testbed (LTB).
+More information about CURENT LTB can be found at the `LTB Repository`_.
+
+.. panels::
+    :card: + intro-card text-center
+    :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex
+
+    ---
+
+    Getting started
+    ^^^^^^^^^^^^^^^
+
+    New to AMS? Check out the getting started guides.
+
+    +++
+
+    .. link-button:: getting-started
+            :type: ref
+            :text: To the getting started guides
+            :classes: btn-block btn-secondary stretched-link
+
+    ---
+
+    Examples
+    ^^^^^^^^
+
+    The examples of using AMS for power system dispatch study.
+
+    +++
+
+    .. link-button:: scripting_examples
+            :type: ref
+            :text: To the examples
+            :classes: btn-block btn-secondary stretched-link
+
+    ---
+
+    Model development guide
+    ^^^^^^^^^^^^^^^^^^^^^^^
+
+    New dispatch modeling in AMS.
+
+    +++
+
+    .. link-button:: development
+            :type: ref
+            :text: To the development guide
+            :classes: btn-block btn-secondary stretched-link
+    ---
+
+    API reference
+    ^^^^^^^^^^^^^
+
+    The API reference of AMS.
+
+    +++
+
+    .. link-button:: api_reference
+            :type: ref
+            :text: To the API reference
+            :classes: btn-block btn-secondary stretched-link
+
+    ---
+    :column: col-12 p-3
+
+    Using AMS for Research?
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+    Please cite our paper [Cui2021]_ if AMS is used in your research for
+    publication.
+
+
+.. [Cui2021] H. Cui, F. Li and K. Tomsovic, "Hybrid Symbolic-Numeric Framework
+       for Power System Modeling and Analysis," in IEEE Transactions on Power
+       Systems, vol. 36, no. 2, pp. 1373-1384, March 2021, doi:
+       10.1109/TPWRS.2020.3017019.
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: AMS Manual
+   :hidden:
+
+   getting_started/index
+   examples/index
+   modeling/index
+   release-notes
+   api

doc/source/modeling/index.rst

@@ -0,0 +1,7 @@
+.. _development:
+
+===========
+Development
+===========
+
+Modeling guide for AMS.

doc/source/release-notes.rst

@@ -0,0 +1,21 @@
+.. _ReleaseNotes:
+
+=============
+Release notes
+=============
+
+The APIs before v3.0.0 are in beta and may change without prior notice.
+
+Pre-v1.0.0
+==========
+
+v0.5 (2023-02-17)
+-------------------
+
+- Base System setup
+- Development preparation
+
+v0.4 (2023-01)
+-------------------
+
+This release outlines the package.