Convert README and CONTRIBUTING to markdown

DiamondLightSource · Mar 15, 2024 · abdd910 · abdd910
1 parent 9356536
commit abdd910
Show file tree

Hide file tree

Showing 8 changed files with 76 additions and 106 deletions.
diff --git a/.github/CONTRIBUTING.md 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/python-copier-template-example/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/python-copier-template-example/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
diff --git a/README.md 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/dls-blueapi.svg)](https://pypi.org/project/dls-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          | <https://github.com/DiamondLightSource/blueapi>
+:---:           | :---:
+PyPI            | `pip install blueapi`
+Docker          | `docker run ghcr.io/diamondlightsource/blueapi:latest`
+Documentation   | <https://diamondlightsource.github.io/blueapi>
+Releases        | <https://github.com/DiamondLightSource/blueapi/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. 
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+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
diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md
@@ -0,0 +1,2 @@
+```{include} ../../.github/CONTRIBUTING.md
+```
diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst
diff --git 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: <!-- README only content
 ```
 
+[concept]: images/blueapi.png
 
 How the documentation is structured
 -----------------------------------

diff --git a/pyproject.toml b/pyproject.toml
@@ -32,7 +32,7 @@ dependencies = [
 ]
 dynamic = ["version"]
 license.file = "LICENSE"
-readme = "README.rst"
+readme = "README.md"
 requires-python = ">=3.9"
 
 [project.optional-dependencies]