From 89fd82dc5b9da2589967788a3d9314b93b953ca9 Mon Sep 17 00:00:00 2001 From: Eva Date: Fri, 18 Oct 2024 11:14:22 +0100 Subject: [PATCH] fixed docs Also added an explanation on schema generation. --- LICENSE | 229 ++-------------- README.md | 46 ++-- docs/conf.py | 81 +++++- docs/{user => }/explanations/data-model.rst | 26 +- ...02-switched-to-using-a-python-skeleton.rst | 0 .../0003-exposed-documents-on-event_model.rst | 2 +- ...004-switched-to-python-copier-template.md} | 2 +- .../explanations/event-descriptors.rst | 0 docs/{user => }/explanations/external.rst | 0 docs/explanations/schema-generation.rst | 22 ++ docs/{user => }/how-to/use-cases.rst | 0 docs/images/bluesky-logo-dark.svg | 1 - docs/images/dls-logo.svg | 11 - docs/images/event-model-logo.svg | 258 ++++++++++++++++++ docs/index.md | 3 +- docs/reference.md | 2 +- docs/{user => }/reference/release-history.rst | 0 docs/tutorials/installation.md | 2 +- pyproject.toml | 2 +- 19 files changed, 428 insertions(+), 259 deletions(-) rename docs/{user => }/explanations/data-model.rst (95%) rename docs/{developer => }/explanations/decisions/0002-switched-to-using-a-python-skeleton.rst (100%) rename docs/{developer => }/explanations/decisions/0003-exposed-documents-on-event_model.rst (88%) rename docs/explanations/decisions/{0002-switched-to-python-copier-template.md => 0004-switched-to-python-copier-template.md} (91%) rename docs/{user => }/explanations/event-descriptors.rst (100%) rename docs/{user => }/explanations/external.rst (100%) create mode 100644 docs/explanations/schema-generation.rst rename docs/{user => }/how-to/use-cases.rst (100%) delete mode 100644 docs/images/bluesky-logo-dark.svg delete mode 100644 docs/images/dls-logo.svg create mode 100644 docs/images/event-model-logo.svg rename docs/{user => }/reference/release-history.rst (100%) diff --git a/LICENSE b/LICENSE index 8dada3eda..eda57e7de 100644 --- a/LICENSE +++ b/LICENSE @@ -1,201 +1,28 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright {yyyy} {name of copyright owner} - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +BSD 3-Clause License + +Copyright (c) 2015, Brookhaven National Laboratory + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md index 11e9d693b..bc4644104 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,38 @@ + + +Data model used by the bluesky ecosystem. + [![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) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -# event_model - -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. +# Event Model -Source | -:---: | :---: -PyPI | `pip install event-model` -Documentation | -Releases | +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 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: +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. -```python -from event_model import __version__ +## Where is my data? -print(f"Hello event_model {__version__}") -``` +For the full details and schema please see the `data_model` section. This is a very quick guide to where +you should look for / put different kinds of information -Or if it is a commandline tool then you might put some example commands here: +* Information about your sample that you know before the measurement → *Start* Document +* What experiment you intended to do → *Start* Document +* Who you are / where you are → *Start* Document +* References to external databases → *Start* Document +* The Data™ → *Event* Document +* Detector calibrations, dark frames, flat fields , or masks → *Event* Document (probably in its own stream) +* The shape / data type / units of The Data™ → *Event Descriptor* Document in the *data_keys* entry +* Anything you read from the controls system that is not device configuration → *Event* Document +* Device configuration data → *Event Descriptor* Document in the *configuration* entry -``` -python -m event_model --version -``` diff --git a/docs/conf.py b/docs/conf.py index bf839abaf..0da4ca5b4 100644 --- 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 b/docs/explanations/data-model.rst similarity index 95% rename from docs/user/explanations/data-model.rst rename to docs/explanations/data-model.rst index d5efeb7ca..162eeaa96 100644 --- a/docs/user/explanations/data-model.rst +++ b/docs/explanations/data-model.rst @@ -59,7 +59,7 @@ Resource and Datum document types manage references to externally-stored data. Example Runs ============ -.. image:: ../../images/document-generation-timeline.svg +.. image:: ../images/document-generation-timeline.svg :width: 100% :align: center @@ -162,7 +162,7 @@ experimetal and subject to backward-incompatible changes in future releases. The run start document formal schema: -.. literalinclude:: ../../../event_model/schemas/run_start.json +.. literalinclude:: ../../src/event_model/schemas/run_start.json .. _descriptor: @@ -241,7 +241,7 @@ Typical example: Formal schema: -.. literalinclude:: ../../../event_model/schemas/event_descriptor.json +.. literalinclude:: ../../src/event_model/schemas/event_descriptor.json .. _event: @@ -298,7 +298,7 @@ overall event 'time' is often more useful. Formal schema: -.. literalinclude:: ../../../event_model/schemas/event.json +.. literalinclude:: ../../src/event_model/schemas/event.json .. _event_page: @@ -326,7 +326,7 @@ the example Event above structured as an Event Page with a single row: Formal Event Page schema: -.. literalinclude:: ../../../event_model/schemas/event_page.json +.. literalinclude:: ../../src/event_model/schemas/event_page.json It is intentional that the values in the "data" and "timestamps" dictionaries do not have structure. The values may be numeric, bool, null (``None``), or a @@ -375,7 +375,7 @@ Typical example: Formal schema: -.. literalinclude:: ../../../event_model/schemas/run_stop.json +.. literalinclude:: ../../src/event_model/schemas/run_stop.json .. _resource: @@ -413,7 +413,7 @@ Typical example: Formal schema: -.. literalinclude:: ../../../event_model/schemas/resource.json +.. literalinclude:: ../../src/event_model/schemas/resource.json .. _datum: @@ -446,7 +446,7 @@ It is an implementation detail that ``datum_id`` is often formatted as Formal schema: -.. literalinclude:: ../../../event_model/schemas/datum.json +.. literalinclude:: ../../src/event_model/schemas/datum.json .. _datum_page: @@ -466,7 +466,7 @@ strucuted as a Datum Page with one row: Formal Datum Page schema: -.. literalinclude:: ../../../event_model/schemas/datum_page.json +.. literalinclude:: ../../src/event_model/schemas/datum_page.json .. _stream_resource: @@ -491,7 +491,7 @@ Typical example: Formal schema: -.. literalinclude:: ../../../event_model/schemas/stream_resource.json +.. literalinclude:: ../../src/event_model/schemas/stream_resource.json .. _stream_datum: @@ -516,7 +516,7 @@ Typical example: Formal schema: -.. literalinclude:: ../../../event_model/schemas/stream_datum.json +.. literalinclude:: ../../src/event_model/schemas/stream_datum.json .. _bulk_events: @@ -526,7 +526,7 @@ Formal schema: This is another representation of Events. This representation is deprecated. Use EventPage instead. -.. literalinclude:: ../../../event_model/schemas/bulk_events.json +.. literalinclude:: ../../src/event_model/schemas/bulk_events.json .. _bulk_datum: @@ -536,4 +536,4 @@ Use EventPage instead. This is another representation of Datum. This representation is deprecated. Use DatumPage instead. -.. literalinclude:: ../../../event_model/schemas/bulk_datum.json +.. literalinclude:: ../../src/event_model/schemas/bulk_datum.json diff --git a/docs/developer/explanations/decisions/0002-switched-to-using-a-python-skeleton.rst b/docs/explanations/decisions/0002-switched-to-using-a-python-skeleton.rst similarity index 100% rename from docs/developer/explanations/decisions/0002-switched-to-using-a-python-skeleton.rst rename to docs/explanations/decisions/0002-switched-to-using-a-python-skeleton.rst diff --git a/docs/developer/explanations/decisions/0003-exposed-documents-on-event_model.rst b/docs/explanations/decisions/0003-exposed-documents-on-event_model.rst similarity index 88% rename from docs/developer/explanations/decisions/0003-exposed-documents-on-event_model.rst rename to docs/explanations/decisions/0003-exposed-documents-on-event_model.rst index 73b564e28..d3dfdb4ef 100644 --- a/docs/developer/explanations/decisions/0003-exposed-documents-on-event_model.rst +++ b/docs/explanations/decisions/0003-exposed-documents-on-event_model.rst @@ -21,4 +21,4 @@ Accepted Consequences ------------ -Repositories downstream will be able to simplify their imports. \ No newline at end of file +Repositories downstream will be able to simplify their imports. diff --git a/docs/explanations/decisions/0002-switched-to-python-copier-template.md b/docs/explanations/decisions/0004-switched-to-python-copier-template.md similarity index 91% rename from docs/explanations/decisions/0002-switched-to-python-copier-template.md rename to docs/explanations/decisions/0004-switched-to-python-copier-template.md index 66fe5d8b2..e2c1d3d88 100644 --- a/docs/explanations/decisions/0002-switched-to-python-copier-template.md +++ b/docs/explanations/decisions/0004-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/user/explanations/event-descriptors.rst b/docs/explanations/event-descriptors.rst similarity index 100% rename from docs/user/explanations/event-descriptors.rst rename to docs/explanations/event-descriptors.rst diff --git a/docs/user/explanations/external.rst b/docs/explanations/external.rst similarity index 100% rename from docs/user/explanations/external.rst rename to docs/explanations/external.rst diff --git a/docs/explanations/schema-generation.rst b/docs/explanations/schema-generation.rst new file mode 100644 index 000000000..8c9485036 --- /dev/null +++ b/docs/explanations/schema-generation.rst @@ -0,0 +1,22 @@ +.. _schema_generation: + +***************** +Schema Generation +***************** + +To allow for python typing of documents, we define them as `TypedDict` in `event_model.documents`. + +.. literalinclude:: ../../src/event_model/documents/datum.py + :language: python + +We then use pydantic to convert these python types into the jsonschema in `event_model.schemas`. + +After changing any of the documents it's necessary to regenerate the schemas. This can be done by running: + +.. code-block:: bash + + regenerate-schema + +which is a python environment script in a dev install of event-model. + +This ensures we can have accurate typing across the bluesky codebase, but also doesn't limit us to python for validating documents. diff --git a/docs/user/how-to/use-cases.rst b/docs/how-to/use-cases.rst similarity index 100% rename from docs/user/how-to/use-cases.rst rename to docs/how-to/use-cases.rst diff --git a/docs/images/bluesky-logo-dark.svg b/docs/images/bluesky-logo-dark.svg deleted file mode 100644 index 0ec005008..000000000 --- a/docs/images/bluesky-logo-dark.svg +++ /dev/null @@ -1 +0,0 @@ -Bluesky_Logo_Final \ No newline at end of file diff --git a/docs/images/dls-logo.svg b/docs/images/dls-logo.svg deleted file mode 100644 index 4fcaa861d..000000000 --- a/docs/images/dls-logo.svg +++ /dev/null @@ -1,11 +0,0 @@ - - - - - - - - - - - diff --git a/docs/images/event-model-logo.svg b/docs/images/event-model-logo.svg new file mode 100644 index 000000000..b7190ae30 --- /dev/null +++ b/docs/images/event-model-logo.svg @@ -0,0 +1,258 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/index.md b/docs/index.md index 730b3fdc1..0ecb86f46 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,10 +3,9 @@ html_theme.sidebar_secondary.remove: true --- ```{include} ../README.md -:end-before: