Merge pull request #11 from pytorch-lumo/dev1

Weakly update 2023.03.19

.github/workflows/gh-pages.yml

@@ -0,0 +1,49 @@
+name: github pages
+
+on:
+  push:
+    branches:
+      - "master"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.8'
+
+      - name: Upgrade pip
+        run: |
+          # install pip=>20.1 to use "pip cache dir"
+          python3 -m pip install --upgrade pip
+
+      - name: Get pip cache dir
+        id: pip-cache
+        run: echo "::set-output name=dir::$(pip cache dir)"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.pip-cache.outputs.dir }}
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install -r ./requirements.txt
+          python3 -m pip install -r ./docs/requirements.txt
+
+      - run: sphinx-build -b html docs/source/ docs/build/html
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build/html
+          #destination_dir: subdir
+          #keep_files: true

.gitignore

@@ -166,4 +166,3 @@ lumo_temp
 wandb
 .lumorc.json
 .lumorc.public.json
-docs/

docs/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)

docs/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
+
+%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
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,5 @@
+sphinx_rtd_theme
+myst_parser
+sphinx
+recommonmark
+sphinx-multiversion

docs/source/conf.py

@@ -0,0 +1,149 @@
+# 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
+import re
+from pathlib import Path
+
+from sphinx.application import Sphinx
+
+version_fn = Path(__file__).parent.parent.parent.joinpath('src/lumo/__init__.py').as_posix()
+
+
+def extract_version():
+    return re.search(
+        r'__version__ = "([\d.d\-]+)"',
+        open(version_fn, 'r', encoding='utf-8').read()).group(1)
+
+
+project = 'lumo'
+copyright = '2023, sailist'
+author = 'sailist'
+release = extract_version()
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../../src/'))
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+from recommonmark.transform import AutoStructify
+from recommonmark.parser import CommonMarkParser
+import commonmark
+
+extensions = [
+    "myst_parser",
+    # "autodoc2",
+
+    "sphinx_multiversion",
+    # "custom_rtd_theme",  # pip install custom_rtd_theme
+    'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
+
+]
+
+
+def docstring(app, what, name, obj, options, lines):
+    md = '\n'.join(lines)
+    ast = commonmark.Parser().parse(md)
+    rst = commonmark.ReStructuredTextRenderer().render(ast)
+    lines.clear()
+    lines += rst.splitlines()
+
+
+def html_page_context(app, pagename, templatename, context, doctree):
+    # versioninfo = VersionInfo(
+    #     app, context, app.config.smv_metadata, app.config.smv_current_version
+    # )
+    context["READTHEDOCS"] = True
+    context["theme_display_version"] = True
+    # context["vhasdoc"] = versioninfo.vhasdoc
+    # context["vpathto"] = versioninfo.vpathto
+    #
+    context["current_version"] = extract_version()
+    # context["latest_version"] = versioninfo[app.config.smv_latest_version]
+    # context["html_theme"] = app.config.html_theme
+    pass
+
+
+def setup(app: Sphinx):
+    app.add_transform(AutoStructify)
+    app.add_config_value('recommonmark_config', {
+        'auto_toc_tree_section': 'Contents',
+    }, True)
+    app.connect('autodoc-process-docstring', docstring)
+    app.connect("html-page-context", html_page_context)
+
+    app.add_html_theme('custom_rtd_theme', Path(__file__).parent.joinpath('custom_rtd_theme/').as_posix())
+
+
+autodoc2_packages = [
+    "../../src/library",
+]
+myst_enable_extensions = [
+    "deflist",
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+
+# html_theme = Path(__file__).parent.joinpath('custom_rtd_theme/').as_posix()
+html_theme = "custom_rtd_theme"
+# html_theme = "sphinx_rtd_theme"
+# html_theme = "alabaster"
+html_theme_options = {
+    # 'github_url': 'https://github.com/pytorch-lumo/lumo',
+    # 'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
+    # 'analytics_anonymize_ip': False,
+    # 'logo_only': False,
+    # 'display_version': True,
+    # 'prev_next_buttons_location': 'bottom',
+    # 'style_external_links': False,
+    # 'vcs_pageview_mode': '',
+    # 'style_nav_header_background': 'white',
+    # # Toc options
+    # 'collapse_navigation': True,
+    # 'sticky_navigation': True,
+    # 'navigation_depth': 4,
+    # 'includehidden': True,
+    # 'titles_only': False
+}
+
+html_static_path = ['_static']
+#
+# source_suffix = {
+#     '.rst': 'restructuredtext',
+#     '.txt': 'markdown',
+#     '.md': 'markdown',
+# }
+#
+commonmark_suffixes = ['.rst']
+
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
+source_suffix = ['.rst', '.md']
+
+# html_sidebars = {
+#     '**': [
+#         # "my_side.html",
+#         # 'versions.html',
+#     ],
+# }
+smv_outputdir_format = f'v{extract_version()}'
+# smv_tag_whitelist = r'^.*$'  # Include all tags
+smv_tag_whitelist = r'^v\d+\.\d+.\d+.\d+$'  # Include tags like "v2.1"

docs/source/custom_rtd_theme/breadcrumbs.html

@@ -0,0 +1,77 @@
+{%- if meta is defined and meta is not none %}
+   {%- set check_meta = True %}
+{%- else %}
+   {%- set check_meta = False %}
+{%- endif %}
+
+{%- if check_meta and 'github_url' in meta %}
+   {%- set display_github = True %}
+{%- endif %}
+
+{%- if check_meta and 'bitbucket_url' in meta %}
+   {%- set display_bitbucket = True %}
+{%- endif %}
+
+{%- if check_meta and 'gitlab_url' in meta %}
+   {%- set display_gitlab = True %}
+{%- endif %}
+
+{%- set display_vcs_links = display_vcs_links if display_vcs_links is defined else True %}
+
+{#- Translators: This is an ARIA section label for page links, including previous/next page link and links to GitHub/GitLab/etc. -#}
+<div role="navigation" aria-label="{{ _('Page navigation') }}">
+  <ul class="wy-breadcrumbs">
+    {%- block breadcrumbs %}
+      <li><a href="{{ pathto(master_doc) }}" class="icon icon-home" aria-label="Home"></a></li>
+        {%- for doc in parents %}
+          <li class="breadcrumb-item"><a href="{{ doc.link|e }}">{{ doc.title }}</a></li>
+        {%- endfor %}
+      <li class="breadcrumb-item active">{{ title }}</li>
+    {%- endblock %}
+    {%- block breadcrumbs_aside %}
+      <li class="wy-breadcrumbs-aside">
+        {%- if hasdoc(pagename) and display_vcs_links %}
+          {%- if display_github %}
+            {%- if check_meta and 'github_url' in meta %}
+              <!-- User defined GitHub URL -->
+              <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {%- else %}
+              <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode or "blob" }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {%- endif %}
+          {%- elif display_bitbucket %}
+            {%- if check_meta and 'bitbucket_url' in meta %}
+              <!-- User defined Bitbucket URL -->
+              <a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {%- else %}
+              <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}?mode={{ theme_vcs_pageview_mode or "view" }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {%- endif %}
+          {%- elif display_gitlab %}
+            {%- if check_meta and 'gitlab_url' in meta %}
+              <!-- User defined GitLab URL -->
+              <a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {%- else %}
+              <a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode or "blob" }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ page_source_suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {%- endif %}
+          {%- elif show_source and source_url_prefix %}
+            <a href="{{ source_url_prefix }}{{ pagename }}{{ page_source_suffix }}">{{ _('View page source') }}</a>
+          {%- elif show_source and has_source and sourcename %}
+            <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> {{ _('View page source') }}</a>
+          {%- endif %}
+        {%- endif %}
+      </li>
+    {%- endblock %}
+  </ul>
+
+  {%- if (theme_prev_next_buttons_location == 'top' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+  {#- Translators: This is an ARIA section label for sequential page links, such as previous and next page links. -#}
+  <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="{{ _('Sequential page navigation') }}">
+      {%- if prev %}
+        <a href="{{ prev.link|e }}" class="btn btn-neutral float-left" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> {{ _('Previous') }}</a>
+      {%- endif %}
+      {%- if next %}
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n">{{ _('Next') }} <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
+      {%- endif %}
+  </div>
+  {%- endif %}
+  <hr/>
+</div>