From d286bbda7b05005b0293a71d45cef6720d0ee8f8 Mon Sep 17 00:00:00 2001
From: lb584 <lb584@cam.ac.uk>
Date: Wed, 31 May 2023 17:21:48 +0100
Subject: [PATCH] fist attempt at building coordinator cods on gitlab
---
.gitignore | 2 +
.gitlab-ci.yml | 12 ++--
docs/Makefile | 22 +++++++
docs/_templates/custom-class-template.rst | 34 +++++++++++
docs/_templates/custom-module-template.rst | 66 ++++++++++++++++++++
docs/api.rst | 13 ++++
docs/conf.py | 70 ++++++++++++++++++++++
docs/index.html | 8 ---
docs/index.rst | 29 +++++++++
9 files changed, 244 insertions(+), 12 deletions(-)
create mode 100644 docs/Makefile
create mode 100644 docs/_templates/custom-class-template.rst
create mode 100644 docs/_templates/custom-module-template.rst
create mode 100644 docs/api.rst
create mode 100644 docs/conf.py
delete mode 100644 docs/index.html
create mode 100644 docs/index.rst
diff --git a/.gitignore b/.gitignore
index 22c1c2a..dc835bb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,3 +14,5 @@ builds/
config/
run_EnvSuitPipeline.py
custom_plotting.py
+/docs/_build/
+/docs/_autosummary/
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 94995bb..f1f1d02 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -281,11 +281,15 @@ full_fat_epi:
pages:
when: always
stage: docs
+ extends: .before_script
+ image: lb584/ews_coordinator:latest
script:
- echo "hello"
- - mkdir public
- - mv -v $CI_PROJECT_DIR/docs/index.html public
- - ls public/
+ - cd $CI_PROJECT_DIR/docs
+ - make html
+ - mkdir $CI_PROJECT_DIR/public
+ - mv -rv $CI_PROJECT_DIR/docs/_build/html/* $CI_PROJECT_DIR/public/
+ - ls $CI_PROJECT_DIR/public/
artifacts:
paths:
- - public
+ - $CI_PROJECT_DIR/public
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..c0cc58c
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,22 @@
+# 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 = .
+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
+ rm -rf _build
+ rm -rf _autosummary
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst
new file mode 100644
index 0000000..f73eda5
--- /dev/null
+++ b/docs/_templates/custom-class-template.rst
@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+ :members:
+ :show-inheritance:
+ :inherited-members:
+ :special-members: __call__, __add__, __mul__
+
+ {% block methods %}
+ {% if methods %}
+ .. rubric:: {{ _('Methods') }}
+
+ .. autosummary::
+ :nosignatures:
+ {% for item in methods %}
+ {%- if not item.startswith('_') %}
+ ~{{ name }}.{{ item }}
+ {%- endif -%}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block attributes %}
+ {% if attributes %}
+ .. rubric:: {{ _('Attributes') }}
+
+ .. autosummary::
+ {% for item in attributes %}
+ ~{{ name }}.{{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst
new file mode 100644
index 0000000..d066d0e
--- /dev/null
+++ b/docs/_templates/custom-module-template.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+ {% block attributes %}
+ {% if attributes %}
+ .. rubric:: Module attributes
+
+ .. autosummary::
+ :toctree:
+ {% for item in attributes %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block functions %}
+ {% if functions %}
+ .. rubric:: {{ _('Functions') }}
+
+ .. autosummary::
+ :toctree:
+ :nosignatures:
+ {% for item in functions %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block classes %}
+ {% if classes %}
+ .. rubric:: {{ _('Classes') }}
+
+ .. autosummary::
+ :toctree:
+ :template: custom-class-template.rst
+ :nosignatures:
+ {% for item in classes %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block exceptions %}
+ {% if exceptions %}
+ .. rubric:: {{ _('Exceptions') }}
+
+ .. autosummary::
+ :toctree:
+ {% for item in exceptions %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+ :toctree:
+ :template: custom-module-template.rst
+ :recursive:
+{% for item in modules %}
+ {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..f15c1b8
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,13 @@
+API
+===
+
+.. autosummary::
+ :toctree: _autosummary
+ :template: custom-module-template.rst
+ :recursive:
+
+ coordinator
+ plotting
+ ews_postprocessing
+ met_processing
+ source_gen
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..64e1d25
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,70 @@
+# 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
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+print(sys.path)
+
+project = 'ews-coordinator'
+author = 'Gilligan lab'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+ 'sphinx.ext.duration',
+ 'sphinx.ext.doctest',
+ 'sphinx.ext.autodoc',
+ 'sphinx.ext.autosummary',
+ 'sphinx.ext.intersphinx', # Link to other project's documentation (see mapping below)
+ 'sphinx.ext.viewcode', # Add a link to the Python source code for classes, functions etc.
+ 'sphinx_autodoc_typehints', # Automatically document param types (less noise in class signature)
+ 'IPython.sphinxext.ipython_console_highlighting'
+]
+
+# Mappings for sphinx.ext.intersphinx. Projects have to have Sphinx-generated doc! (.inv file)
+intersphinx_mapping = {
+ "python": ("https://docs.python.org/3/", None),
+}
+
+autosummary_generate = True # Turn on sphinx.ext.autosummary
+autoclass_content = "both" # Add __init__ doc (ie. params) to class summaries
+html_show_sourcelink = False # Remove 'view source code' from top of page (for html, not python)
+autodoc_inherit_docstrings = True # If no docstring, inherit from base class
+set_type_checking_flag = True # Enable 'expensive' imports for sphinx_autodoc_typehints
+nbsphinx_allow_errors = True
+autodoc_typehints = "description" # Sphinx-native method. Not as good as sphinx_autodoc_typehints
+add_module_names = False # Remove namespaces from class/method signatures
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# Readthedocs theme
+# on_rtd is whether on readthedocs.org, this line of code grabbed from docs.readthedocs.org...
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+if not on_rtd: # only import and set the theme if we're building docs locally
+ import sphinx_rtd_theme
+ html_theme = "sphinx_rtd_theme"
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_css_files = ["readthedocs-custom.css"] # Override some CSS settings
+# html_theme = 'alabaster'
+
+
+# # This is the expected signature of the handler for this event, cf doc
+# def autodoc_skip_member_handler(app, what, name, obj, skip, options):
+# # Basic approach; you might want a regex instead
+# print("got it" + name)
+# return name.startswith("test_")
+#
+#
+# # Automatically called by sphinx at startup
+# def setup(app):
+# # Connect the autodoc-skip-member event from apidoc to the callback
+# app.connect('autodoc-skip-member', autodoc_skip_member_handler)
+
diff --git a/docs/index.html b/docs/index.html
deleted file mode 100644
index cc70e23..0000000
--- a/docs/index.html
+++ /dev/null
@@ -1,8 +0,0 @@
-<html>
- <head>
- <title>Home</title>
- </head>
- <body>
- <h1>Hello World!</h1>
- </body>
- </html>
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..211b359
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,29 @@
+.. ews-plotting documentation master file, created by
+ sphinx-quickstart on Thu May 25 13:28:43 2023.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to ews-plotting's documentation!
+========================================
+
+
+.. toctree::
+ :hidden:
+
+ Home page <self>
+ coordinator API <_autosummary/coordinator>
+ plotting API <_autosummary/plotting>
+ post processing API <_autosummary/ews_postprocessing>
+ met processing processing API <_autosummary/met_processing>
+ source gen API <_autosummary/source_gen>
+
+
+Indices and tables
+==================
+
+this is is a load of ``text`` that has ``plotting.common.utils`` this function in it
+
+.. autosummary::
+ plotting.common.utils.build_standard_depo_diseases
+ ews_postprocessing.deposition.NAME_to_csv.NAMEToCSV
+
--
GitLab