diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/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) diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..061f32f --- /dev/null +++ b/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 diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..2e05197 --- /dev/null +++ b/doc/source/api.rst @@ -0,0 +1,7 @@ +.. _api_reference: + +============= +API reference +============= + + diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..9056741 --- /dev/null +++ b/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 diff --git a/doc/source/examples/index.rst b/doc/source/examples/index.rst new file mode 100644 index 0000000..faed285 --- /dev/null +++ b/doc/source/examples/index.rst @@ -0,0 +1,4 @@ +.. _scripting_examples: + +Examples +======== diff --git a/doc/source/genroutineref.py b/doc/source/genroutineref.py new file mode 100644 index 0000000..05cf809 --- /dev/null +++ b/doc/source/genroutineref.py @@ -0,0 +1,3 @@ +""" +This file is used to generate reStructuredText tables for Routine references. +""" \ No newline at end of file diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst new file mode 100644 index 0000000..65fb479 --- /dev/null +++ b/doc/source/getting_started/index.rst @@ -0,0 +1,21 @@ + +.. raw:: html + + +

AMS

+ +

+ Python Library for Power System Dispatch Modeling and Dispatch-Dynamic Co-Simulation

+ + +.. _getting-started: + +=============== +Getting started +=============== + +.. toctree:: + :maxdepth: 3 + :hidden: diff --git a/doc/source/images/curent.ico b/doc/source/images/curent.ico new file mode 100644 index 0000000..cd5da49 Binary files /dev/null and b/doc/source/images/curent.ico differ diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..da4bc7a --- /dev/null +++ b/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 diff --git a/doc/source/modeling/index.rst b/doc/source/modeling/index.rst new file mode 100644 index 0000000..7cf3934 --- /dev/null +++ b/doc/source/modeling/index.rst @@ -0,0 +1,7 @@ +.. _development: + +=========== +Development +=========== + +Modeling guide for AMS. \ No newline at end of file diff --git a/doc/about.md b/doc/source/old/about.md similarity index 100% rename from doc/about.md rename to doc/source/old/about.md diff --git a/doc/advanced_usage.md b/doc/source/old/advanced_usage.md similarity index 100% rename from doc/advanced_usage.md rename to doc/source/old/advanced_usage.md diff --git a/doc/basic_usage.md b/doc/source/old/basic_usage.md similarity index 100% rename from doc/basic_usage.md rename to doc/source/old/basic_usage.md diff --git a/doc/data_and_models.md b/doc/source/old/data_and_models.md similarity index 100% rename from doc/data_and_models.md rename to doc/source/old/data_and_models.md diff --git a/doc/img/accuracy_039_1.png b/doc/source/old/img/accuracy_039_1.png similarity index 100% rename from doc/img/accuracy_039_1.png rename to doc/source/old/img/accuracy_039_1.png diff --git a/doc/img/accuracy_039_2.png b/doc/source/old/img/accuracy_039_2.png similarity index 100% rename from doc/img/accuracy_039_2.png rename to doc/source/old/img/accuracy_039_2.png diff --git a/doc/img/comp_speed_458.png b/doc/source/old/img/comp_speed_458.png similarity index 100% rename from doc/img/comp_speed_458.png rename to doc/source/old/img/comp_speed_458.png diff --git a/doc/img/comp_time_039.png b/doc/source/old/img/comp_time_039.png similarity index 100% rename from doc/img/comp_time_039.png rename to doc/source/old/img/comp_time_039.png diff --git a/doc/img/contingency_458.png b/doc/source/old/img/contingency_458.png similarity index 100% rename from doc/img/contingency_458.png rename to doc/source/old/img/contingency_458.png diff --git a/doc/img/ssa_benchmarking.png b/doc/source/old/img/ssa_benchmarking.png similarity index 100% rename from doc/img/ssa_benchmarking.png rename to doc/source/old/img/ssa_benchmarking.png diff --git a/doc/index.md b/doc/source/old/index.md similarity index 100% rename from doc/index.md rename to doc/source/old/index.md diff --git a/doc/installation.md b/doc/source/old/installation.md similarity index 100% rename from doc/installation.md rename to doc/source/old/installation.md diff --git a/doc/sas_basics.md b/doc/source/old/sas_basics.md similarity index 100% rename from doc/sas_basics.md rename to doc/source/old/sas_basics.md diff --git a/doc/source/release-notes.rst b/doc/source/release-notes.rst new file mode 100644 index 0000000..12a4e54 --- /dev/null +++ b/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. \ No newline at end of file