From 503811c1d277994ad4acdb8f53e8c2d1e7943217 Mon Sep 17 00:00:00 2001 From: Joe Shannon Date: Fri, 15 Mar 2024 15:11:02 +0000 Subject: [PATCH 1/2] Convert README and CONTRIBUTING to markdown (#394) Fixes #391. --- .github/CONTRIBUTING.md | 27 ++++++++++++++++ .github/CONTRIBUTING.rst | 35 -------------------- README.md | 43 +++++++++++++++++++++++++ README.rst | 66 -------------------------------------- docs/how-to/contribute.md | 2 ++ docs/how-to/contribute.rst | 1 - docs/index.md | 6 ++-- pyproject.toml | 2 +- 8 files changed, 76 insertions(+), 106 deletions(-) create mode 100644 .github/CONTRIBUTING.md delete mode 100644 .github/CONTRIBUTING.rst create mode 100644 README.md delete mode 100644 README.rst create mode 100644 docs/how-to/contribute.md delete mode 100644 docs/how-to/contribute.rst diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..05162541c --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,27 @@ +# Contribute to the project + +Contributions and issues are most welcome! All issues and pull requests are +handled through [GitHub](https://github.com/DiamondLightSource/blueapi/issues). Also, please check for any existing issues before +filing a new one. If you have a great idea but it involves big changes, please +file a ticket before making a pull request! We want to make sure you don't spend +your time coding something that might not fit the scope of the project. + +## Issue or Discussion? + +Github also offers [discussions](https://github.com/DiamondLightSource/blueapi/discussions) as a place to ask questions and share ideas. If +your issue is open ended and it is not obvious when it can be "closed", please +raise it as a discussion instead. + +## Code Coverage + +While 100% code coverage does not make a library bug-free, it significantly +reduces the number of easily caught bugs! Please make sure coverage remains the +same or is improved by a pull request! + +## Developer Information + +It is recommended that developers use a [vscode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). This repository contains configuration to set up a containerized development environment that suits its own needs. + +This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects. + +For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/2.0.1/how-to.html). diff --git a/.github/CONTRIBUTING.rst b/.github/CONTRIBUTING.rst deleted file mode 100644 index 7ccd66dce..000000000 --- a/.github/CONTRIBUTING.rst +++ /dev/null @@ -1,35 +0,0 @@ -Contributing to the project -=========================== - -Contributions and issues are most welcome! All issues and pull requests are -handled through GitHub_. Also, please check for any existing issues before -filing a new one. If you have a great idea but it involves big changes, please -file a ticket before making a pull request! We want to make sure you don't spend -your time coding something that might not fit the scope of the project. - -.. _GitHub: https://github.com/DiamondLightSource/blueapi/issues - -Issue or Discussion? --------------------- - -Github also offers discussions_ as a place to ask questions and share ideas. If -your issue is open ended and it is not obvious when it can be "closed", please -raise it as a discussion instead. - -.. _discussions: https://github.com/DiamondLightSource/blueapi/discussions - -Code coverage -------------- - -While 100% code coverage does not make a library bug-free, it significantly -reduces the number of easily caught bugs! Please make sure coverage remains the -same or is improved by a pull request! - -Developer guide ---------------- - -The `Developer Guide`_ contains information on setting up a development -environment, running the tests and what standards the code and documentation -should follow. - -.. _Developer Guide: https://diamondlightsource.github.io/blueapi/main/developer/how-to/contribute.html diff --git a/README.md b/README.md new file mode 100644 index 000000000..e98719889 --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +[![CI](https://github.com/DiamondLightSource/blueapi/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/blueapi/actions/workflows/ci.yml) +[![Coverage](https://codecov.io/gh/DiamondLightSource/blueapi/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/blueapi) +[![PyPI](https://img.shields.io/pypi/v/blueapi.svg)](https://pypi.org/project/blueapi) +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) + +# blueapi + +Lightweight bluesky-as-a-service wrapper application. Also usable as a library. + +Source | +:---: | :---: +PyPI | `pip install blueapi` +Docker | `docker run ghcr.io/diamondlightsource/blueapi:latest` +Documentation | +Releases | + +This module wraps [bluesky](https://blueskyproject.io/bluesky) plans and devices +inside a server and exposes endpoints to send commands/receive data. Useful for +installation at labs where multiple people may control equipment, possibly from +remote locations. + +![concept][] + +The main premise of blueapi is to minimize the boilerplate required to get plans +and devices up and running by generating an API for your lab out of +type-annotated plans. For example, take the following plan: + +```python + import bluesky.plans as bp + from blueapi.core import MsgGenerator + + def my_plan(foo: str, bar: int) -> MsgGenerator: + yield from bp.scan(...) +``` + +Blueapi's job is to detect this plan and automatically add it to the lab's API +so it can be invoked easily with a few REST calls. + + + +See https://diamondlightsource.github.io/blueapi for more detailed documentation. + +[concept]: https://raw.githubusercontent.com/DiamondLightSource/blueapi/main/docs/images/blueapi.png diff --git a/README.rst b/README.rst deleted file mode 100644 index 93f1e3c49..000000000 --- a/README.rst +++ /dev/null @@ -1,66 +0,0 @@ -blueapi -=========================== - -|code_ci| |docs_ci| |coverage| |pypi_version| |license| - -Lightweight bluesky-as-a-service wrapper application. Also usable as a library. - -============== ============================================================== -PyPI ``pip install blueapi`` -Source code https://github.com/DiamondLightSource/blueapi -Documentation https://DiamondLightSource.github.io/blueapi -Releases https://github.com/DiamondLightSource/blueapi/releases -============== ============================================================== - -This module wraps bluesky_ plans and devices inside a server and exposes endpoints to send commands/receive data. -Useful for installation at labs where multiple people may control equipment, -possibly from remote locations. - -|concept| - -The main premise of blueapi is to minimize the boilerplate required to get plans -and devices up and running by generating an API for your lab out of type-annotated -plans. For example, take the following plan: - -.. code:: python - - import bluesky.plans as bp - from blueapi.core import MsgGenerator - - def my_plan(foo: str, bar: int) -> MsgGenerator: - yield from bp.scan(...) - -Blueapi's job is to detect this plan and automatically add it to the lab's API so it -can be invoked easily with a few REST calls. - -.. _bluesky: https://blueskyproject.io/bluesky - -.. |code_ci| image:: https://github.com/DiamondLightSource/blueapi/actions/workflows/code.yml/badge.svg?branch=main - :target: https://github.com/DiamondLightSource/blueapi/actions/workflows/code.yml - :alt: Code CI - -.. |docs_ci| image:: https://github.com/DiamondLightSource/blueapi/actions/workflows/docs.yml/badge.svg?branch=main - :target: https://github.com/DiamondLightSource/blueapi/actions/workflows/docs.yml - :alt: Docs CI - -.. |coverage| image:: https://codecov.io/gh/DiamondLightSource/blueapi/branch/main/graph/badge.svg - :target: https://codecov.io/gh/DiamondLightSource/blueapi - :alt: Test Coverage - -.. |pypi_version| image:: https://img.shields.io/pypi/v/blueapi.svg - :target: https://pypi.org/project/blueapi - :alt: Latest PyPI version - -.. |license| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg - :target: https://opensource.org/licenses/Apache-2.0 - :alt: Apache License - -.. - Anything below this line is used when viewing README.rst and will be replaced - when included in index.rst - - -.. |concept| image:: docs/images/blueapi.png - :width: 800px - -See https://DiamondLightSource.github.io/blueapi for more detailed documentation. diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md new file mode 100644 index 000000000..f9c4ca1d7 --- /dev/null +++ b/docs/how-to/contribute.md @@ -0,0 +1,2 @@ +```{include} ../../.github/CONTRIBUTING.md +``` \ No newline at end of file diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst deleted file mode 100644 index 65b72c8e0..000000000 --- a/docs/how-to/contribute.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../.github/CONTRIBUTING.rst diff --git a/docs/index.md b/docs/index.md index ed4d277d1..6bfac05b7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,11 +2,11 @@ html_theme.sidebar_secondary.remove: true --- -```{include} ../README.rst -:relative-images: -:end-before: and will be replaced +```{include} ../README.md +:end-before: