fixed docs

bluesky · Oct 18, 2024 · 73def7b · 73def7b
1 parent 35ab716
commit 73def7b
Show file tree

Hide file tree

Showing 16 changed files with 348 additions and 38 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,6 @@
+<img src="https://raw.githubusercontent.com/bluesky/artwork/refs/heads/main/logos/event-model/SVGs/bluesky_event-model_logo_WithSmBsky.svg?token=GHSAT0AAAAAACXB6OZGI7TXFCWRJ7LJMEGCZYSF2PA"
+     style="background: none" width="120px" height="120px" align="right">
+
 [![CI](https://github.com/bluesky/event-model/actions/workflows/ci.yml/badge.svg)](https://github.com/bluesky/event-model/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/bluesky/event-model/branch/main/graph/badge.svg)](https://codecov.io/gh/bluesky/event-model)
 [![PyPI](https://img.shields.io/pypi/v/event-model.svg)](https://pypi.org/project/event-model)
@@ -7,31 +10,19 @@
 
 Data model used by the bluesky ecosystem.
 
-This is where you should write a short paragraph that describes what your module does,
-how it does it, and why people should use it.
+
+A primary design goal of bluesky is to enable better research by recording rich metadata alongside measured data for use in later analysis. Documents are how we do this.
+
+This repository contains the formal schemas for bluesky’s streaming data model and some Python tooling for composing, validating, and transforming documents in the model.
 
 Source          | <https://github.com/bluesky/event-model>
 :---:           | :---:
 PyPI            | `pip install event-model`
 Documentation   | <https://bluesky.github.io/event-model>
 Releases        | <https://github.com/bluesky/event-model/releases>
 
-This is where you should put some images or code snippets that illustrate
-some relevant examples. If it is a library then you might put some
-introductory code here:
-
-```python
-from event_model import __version__
-
-print(f"Hello event_model {__version__}")
-```
-
-Or if it is a commandline tool then you might put some example commands here:
-
-```
-python -m event_model --version
-```
+To regenerate jsonschema after changing documents simply type `regenerate-schema` in a developer venv.
 
-<!-- README only content. Anything below this line won't be included in index.md -->
+-<!-- README only content. Anything below this line won't be included in index.md -->
 
 See https://bluesky.github.io/event-model for more detailed documentation.
diff --git a/docs/conf.py b/docs/conf.py
@@ -17,6 +17,10 @@
 
 # General information about the project.
 project = "event-model"
+copyright = "2019, Brookhaven National Lab"
+author = "Brookhaven National Lab"
+
+language = "en"
 
 # The full version, including alpha/beta/rc tags.
 release = event_model.__version__
@@ -47,16 +51,27 @@
     "sphinx_copybutton",
     # For the card element
     "sphinx_design",
+    "sphinx_design", 
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.githubpages",
+    "matplotlib.sphinxext.plot_directive",
+    "sphinx_copybutton",
+    "IPython.sphinxext.ipython_directive",
+    "IPython.sphinxext.ipython_console_highlighting",
+
     # So we can write markdown files
     "myst_parser",
 ]
 
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
 # So we can use the ::: syntax
 myst_enable_extensions = ["colon_fence"]
 
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
-nitpicky = True
+nitpicky = False
 
 # A list of (type, target) tuples (by default empty) that should be ignored when
 # generating warnings in "nitpicky mode". Note that type should include the
@@ -104,16 +119,37 @@
 # These patterns also affect html_static_path and html_extra_path
 exclude_patterns = ["_build"]
 
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
 # This means you can link things like `str` and `asyncio` to the relevant
 # docs in the python documentation.
-intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "cachetools": ("https://cachetools.readthedocs.io/en/stable/", 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),
+    "jsonschema": ("https://python-jsonschema.readthedocs.io/en/stable/", None),
+}
 
 # A dictionary of graphviz graph attributes for inheritance diagrams.
 inheritance_graph_attrs = {"rankdir": "TB"}
 
+# Common links that should be available on every page
+rst_epilog = """
+.. _NSLS: https://www.bnl.gov/nsls2
+.. _black: https://github.com/psf/black
+.. _flake8: https://flake8.pycqa.org/en/latest/
+.. _isort: https://github.com/PyCQA/isort
+.. _mypy: http://mypy-lang.org/
+.. _pre-commit: https://pre-commit.com/
+"""
+
 # Ignore localhost links for periodic check that links in docs are valid
 linkcheck_ignore = [r"http://localhost:\d+/"]
 
@@ -122,6 +158,43 @@
 copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
 copybutton_prompt_is_regexp = True
 
+# -- Options for manual page output ---------------------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (
+        master_doc,
+        "event-model.tex",
+        "Bluesky Event Model Documentation",
+        "Contributors",
+        "manual",
+    ),
+]
+
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, "event-model", "Bluesky Event Model Documentation", [author], 1)
+]
+
+# 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,
+        "event-model",
+        "Bluesky Event Model Documentation",
+        author,
+        "event-model",
+        "Data model used by the bluesky ecosystem",
+        "Miscellaneous",
+    ),
+]
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -130,7 +203,7 @@
 html_theme = "pydata_sphinx_theme"
 github_repo = "event-model"
 github_user = "bluesky"
-switcher_json = f"https://{github_user}.github.io/{github_repo}/switcher.json"
+switcher_json = f"https://blueskyproject.io/{github_repo}/switcher.json"
 switcher_exists = requests.get(switcher_json).ok
 if not switcher_exists:
     print(
@@ -187,5 +260,5 @@
 html_show_copyright = False
 
 # Logo
-html_logo = "images/dls-logo.svg"
+html_logo = "images/event-model-logo.svg"
 html_favicon = html_logo
diff --git a/docs/user/explanations/data-model.rst → docs/explanations/data-model.rst b/docs/user/explanations/data-model.rst → docs/explanations/data-model.rst
diff --git a/...2-switched-to-using-a-python-skeleton.rst → ...2-switched-to-using-a-python-skeleton.rst b/...2-switched-to-using-a-python-skeleton.rst → ...2-switched-to-using-a-python-skeleton.rst
diff --git a/...0003-exposed-documents-on-event_model.rst → ...0003-exposed-documents-on-event_model.rst b/...0003-exposed-documents-on-event_model.rst → ...0003-exposed-documents-on-event_model.rst
@@ -21,4 +21,4 @@ Accepted
 
 Consequences
 ------------
-Repositories downstream will be able to simplify their imports.
+Repositories downstream will be able to simplify their imports.
diff --git a/...002-switched-to-python-copier-template.md → ...004-switched-to-python-copier-template.md b/...002-switched-to-python-copier-template.md → ...004-switched-to-python-copier-template.md
@@ -1,4 +1,4 @@
-# 2. Adopt python-copier-template for project structure
+# 4. Adopt python-copier-template for project structure
 
 ## Status
 

diff --git a/docs/explanations/decisions.md → docs/explanations/decisions/decisions.md b/docs/explanations/decisions.md → docs/explanations/decisions/decisions.md
diff --git a/docs/user/explanations/event-descriptors.rst → docs/explanations/event-descriptors.rst b/docs/user/explanations/event-descriptors.rst → docs/explanations/event-descriptors.rst
diff --git a/docs/user/explanations/external.rst → docs/explanations/external.rst b/docs/user/explanations/external.rst → docs/explanations/external.rst
diff --git a/docs/user/how-to/use-cases.rst → docs/how-to/use-cases.rst b/docs/user/how-to/use-cases.rst → docs/how-to/use-cases.rst
diff --git a/docs/images/bluesky-logo-dark.svg b/docs/images/bluesky-logo-dark.svg
diff --git a/docs/images/dls-logo.svg b/docs/images/dls-logo.svg