diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index 87fdd4be..7606057e 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -6,6 +6,7 @@ on: - master - develop - '!gh-pages' + - changedocs tags: '*' jobs: @@ -19,6 +20,7 @@ jobs: uses: actions/checkout@v2 with: path: main + fetch-depth: 0 - name: Checkout gh-pages uses: actions/checkout@v2 @@ -38,6 +40,8 @@ jobs: pip install tox tox-gh-actions - name: Build docs with tox + env: + TARGET_NAME: ${{ env.GITHUB_REF_SLUG }} run: | cd main tox -e docs diff --git a/docs/sphinx/manual/_templates/versions.html b/docs/sphinx/manual/_templates/versions.html new file mode 100644 index 00000000..fb30ded1 --- /dev/null +++ b/docs/sphinx/manual/_templates/versions.html @@ -0,0 +1,47 @@ +{# The original version of this file is a part of sphinx_rtd_theme v0.5.0, which is distributed under the MIT license #} +{# https://github.com/readthedocs/sphinx_rtd_theme #} + +{# Add rst-badge after rst-versions for small badge style. #} +{% if ENABLE_VERSIONING == "true" %} +
+ + Read the Docs + v: {{ current_version }} + + +
+
+
{{ _('Languages') }}
+ {% for lang in languages %} + {% set root_dir = pathto("../..", 1)%} +
+ {% if lang == current_lang %}{% endif %} + {{ lang }} + {% if lang == current_lang %}{% endif %} +
+ {% endfor %} + +
{{ _('Branches') }}
+ {% for name in branches %} + {% set root_dir = pathto("../..", 1)%} +
+ {% if name == current_version %}{% endif %} + {{ name }} + {% if name == current_version %}{% endif %} +
+ {% endfor %} + +
{{ _('Tags') }}
+ {% for name in tags %} + {% set root_dir = pathto("../..", 1)%} +
+ {% if name == current_version %}{% endif %} + {{ name }} + {% if name == current_version %}{% endif %} +
+ {% endfor %} + +
+
+
+{% endif %} {# endif ENABLE_VERSIONING #} diff --git a/docs/sphinx/manual/en/source/conf.py b/docs/sphinx/manual/en/source/conf.py index 1de846ce..2c38cee7 100644 --- a/docs/sphinx/manual/en/source/conf.py +++ b/docs/sphinx/manual/en/source/conf.py @@ -22,7 +22,8 @@ import sys import os -sys.path.insert(0, os.path.abspath('../../../../../physbo')) + +sys.path.insert(0, os.path.abspath("../../../../../physbo")) # -- Project information ----------------------------------------------------- @@ -40,20 +41,27 @@ from recommonmark.parser import CommonMarkParser source_parsers = { - '.md': CommonMarkParser, + ".md": CommonMarkParser, } from recommonmark.transform import AutoStructify -github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/' +github_doc_root = "https://github.com/rtfd/recommonmark/tree/master/doc/" + + def setup(app): - app.add_config_value('recommonmark_config', { - 'url_resolver': lambda url: github_doc_root + url, - 'auto_toc_tree_section': 'Contents', - }, True) + app.add_config_value( + "recommonmark_config", + { + "url_resolver": lambda url: github_doc_root + url, + "auto_toc_tree_section": "Contents", + }, + True, + ) app.add_transform(AutoStructify) -pygments_style = 'sphinx' + +pygments_style = "sphinx" nbsphinx_execute = "never" # -- General configuration ------------------------------------------------ @@ -81,47 +89,33 @@ def setup(app): numfig = True # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["../../_templates"] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', '**.ipynb_checkpoints'] -for t in ('tag-latex', 'tag-latexpdf', 'tag-latexpdfja'): +exclude_patterns = ["_build", "**.ipynb_checkpoints"] +for t in ("tag-latex", "tag-latexpdf", "tag-latexpdfja"): if t in tags: - exclude_patterns.append('api') + exclude_patterns.append("api") # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -source_suffix = ['.rst', '.md'] +source_suffix = [".rst", ".md"] # The master toctree document. -master_doc = 'index' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = u'1.0.0' -# The full version, including alpha/beta/rc tags. -release = u'1.0.0' +master_doc = "index" # 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' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] +language = "en" # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -132,47 +126,42 @@ def setup(app): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = "sphinx_rtd_theme" html_log = "logo.png" -html_theme_options = { - 'logo_only': True -} +html_theme_options = {"logo_only": True} # 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 = { - 'font_family': 'Helvetica', - 'sidebar_search_button': 'pink_1' -} +html_theme_options = {"font_family": "Helvetica", "sidebar_search_button": "pink_1"} # 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 = ["../../_static"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # This is required for the alabaster theme # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars -html_sidebars = { - '**': [ - 'about.html', - 'navigation.html', - 'relations.html', - 'searchbox.html', - 'donate.html', - ] -} +# html_sidebars = { +# "**": [ +# "about.html", +# "navigation.html", +# "relations.html", +# "searchbox.html", +# "donate.html", +# ] +# } # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. -htmlhelp_basename = 'PHYSBOdoc' +htmlhelp_basename = "PHYSBOdoc" # -- Options for LaTeX output --------------------------------------------- @@ -181,15 +170,12 @@ def setup(app): # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. # # 'preamble': '', - # Latex figure (float) alignment # # 'figure_align': 'htbp', @@ -199,8 +185,14 @@ def setup(app): # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index','PHYSBO_en.tex', u'PHYSBO Documentation', - u'PHYSBO\'s team', 'manual', 'True'), + ( + "index", + "PHYSBO_en.tex", + u"PHYSBO Documentation", + u"PHYSBO's team", + "manual", + "True", + ), ] @@ -208,12 +200,9 @@ def setup(app): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'PHYSBO', u'PHYSBO Documentation', - [author], 1) -] +man_pages = [(master_doc, "PHYSBO", u"PHYSBO Documentation", [author], 1)] -#latex_docclass = {'manual': 'jsbook'} +# latex_docclass = {'manual': 'jsbook'} latex_logo = "../../_static/logo.png" # -- Options for Texinfo output ------------------------------------------- @@ -222,7 +211,47 @@ def setup(app): # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'PHYSBO', u'PHYSBO Documentation', - author, 'PHYSBO', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "PHYSBO", + u"PHYSBO Documentation", + author, + "PHYSBO", + "One line description of project.", + "Miscellaneous", + ), ] + +# -- configuring _template/version.html ------------------------------------- + +html_context = {} + +html_context["ENABLE_VERSIONING"] = os.environ.get("CI", "false") + +html_context["languages"] = [("en"), ("ja")] +html_context["current_lang"] = language + +current_version = os.environ.get("TARGET_NAME", "") +if not current_version: + current_version = release +html_context["current_version"] = current_version + +html_context["branches"] = ["develop", "master"] +html_context["tags"] = [] +exclude_tags = ["v0.1.0", "v0.2.0", "v0.3.0"] + +try: + import git + + repo = git.Repo(search_parent_directories=True) + tags = list(map(str, repo.tags)) + tags.sort(reverse=True) + for tag in tags: + if tag not in exclude_tags: + html_context["tags"].append(tag) +except: + pass + +if current_version not in html_context["branches"]: + if current_version not in html_context["tags"]: + html_context["branches"].append(current_version) diff --git a/docs/sphinx/manual/ja/source/conf.py b/docs/sphinx/manual/ja/source/conf.py index 3b45821b..9a23ac05 100644 --- a/docs/sphinx/manual/ja/source/conf.py +++ b/docs/sphinx/manual/ja/source/conf.py @@ -16,7 +16,8 @@ import sys import os -sys.path.insert(0, os.path.abspath('../../../../../physbo')) + +sys.path.insert(0, os.path.abspath("../../../../../physbo")) # -- Project information ----------------------------------------------------- @@ -47,8 +48,10 @@ "nbsphinx", ] +numfig = True + # Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] +templates_path = ["../../_templates"] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -60,21 +63,21 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', '**.ipynb_checkpoints'] -for t in ('tag-latex', 'tag-latexpdf', 'tag-latexpdfja'): +exclude_patterns = ["_build", "**.ipynb_checkpoints"] +for t in ("tag-latex", "tag-latexpdf", "tag-latexpdfja"): if t in tags: - exclude_patterns.append('api') + exclude_patterns.append("api") # The suffix of source filenames. -source_suffix = ['.rst', '.md'] +source_suffix = [".rst", ".md"] from recommonmark.parser import CommonMarkParser source_parsers = { - '.md': CommonMarkParser, + ".md": CommonMarkParser, } -pygments_style = 'sphinx' +pygments_style = "sphinx" nbsphinx_execute = "never" @@ -86,9 +89,7 @@ # html_theme = "alabaster" html_theme = "sphinx_rtd_theme" html_log = "logo.png" -html_theme_options = { - 'logo_only': True -} +html_theme_options = {"logo_only": True} # 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, @@ -100,5 +101,40 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). -latex_docclass = {'manual': 'jsbook'} +latex_docclass = {"manual": "jsbook"} latex_logo = "../../_static/logo.png" + + +# -- configuring _template/version.html ------------------------------------- + +html_context = {} + +html_context["ENABLE_VERSIONING"] = os.environ.get("CI", "false") + +html_context["languages"] = [("en"), ("ja")] +html_context["current_lang"] = language + +current_version = os.environ.get("TARGET_NAME", "") +if not current_version: + current_version = release +html_context["current_version"] = current_version + +html_context["branches"] = ["develop", "master"] +html_context["tags"] = [] +exclude_tags = ["v0.1.0", "v0.2.0", "v0.3.0"] + +try: + import git + + repo = git.Repo(search_parent_directories=True) + tags = list(map(str, repo.tags)) + tags.sort(reverse=True) + for tag in tags: + if tag not in exclude_tags: + html_context["tags"].append(tag) +except: + pass + +if current_version not in html_context["branches"]: + if current_version not in html_context["tags"]: + html_context["branches"].append(current_version) diff --git a/tox.ini b/tox.ini index 21d0b642..81a5390f 100644 --- a/tox.ini +++ b/tox.ini @@ -29,6 +29,7 @@ deps = nbsphinx pybtex whitelist_externals = rm +passenv = CI TARGET_NAME commands = rm -rf docs/sphinx/manual/ja/source/api