Convert index to md

README.md

@@ -0,0 +1,74 @@
+# ![logo][] scanspec
+
+[![CI](https://github.com/dls-controls/scanspec/actions/workflows/code.yml/badge.svg)](https://github.com/dls-controls/scanspec/actions/workflows/code.yml)
+[![Coverage](https://codecov.io/gh/dls-controls/scanspec/branch/master/graph/badge.svg)](https://codecov.io/gh/dls-controls/scanspec)
+[![PyPI](https://img.shields.io/pypi/v/scanspec.svg)](https://pypi.org/project/scanspec)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Specify step and flyscan Paths using combinations of:
+
+- Specs like Line or Spiral
+- Optionally Snaking
+- Zip, Product and Concat to compose
+- Masks with multiple Regions to restrict
+
+Serialize the Spec rather than the expanded Path and reconstruct it on the
+server. It can them be iterated over like a [cycler][], or a stack of scan Frames
+can be produced and expanded Paths created to consume chunk by chunk.
+
+[cycler]: https://matplotlib.org/cycler/
+
+Source          | <https://github.com/dls-controls/scanspec>
+---             | ---
+PyPI            | `pip install scanspec`
+Documentation   | <https://dls-controls.github.io/scanspec>
+Releases        | <https://github.com/dls-controls/scanspec/releases>
+
+An example ScanSpec of a 2D snaked grid flyscan inside a circle spending 0.4s at
+each point looks like:
+
+```python
+from scanspec.specs import Line, fly
+from scanspec.regions import Circle
+
+grid = Line(y, 2.1, 3.8, 12) * ~Line(x, 0.5, 1.5, 10)
+spec = fly(grid, 0.4) & Circle(x, y, 1.0, 2.8, radius=0.5)
+```
+
+![plot][]
+
+You can then either iterate through the scan positions directly for convenience:
+
+```python
+for point in spec.midpoints():
+    print(point)
+# ...
+# {'y': 3.1818181818181817, 'x': 0.8333333333333333, 'DURATION': 0.4}
+# {'y': 3.1818181818181817, 'x': 0.7222222222222222, 'DURATION': 0.4}
+```
+
+or create a Path from the stack of Frames and consume chunks of a given length
+from it for performance:
+
+```python
+from scanspec.core import Path
+
+stack = spec.calculate()
+len(stack[0])  # 44
+stack[0].axes()  # ['y', 'x', 'DURATION']
+
+path = Path(stack, start=5, num=30)
+chunk = path.consume(10)
+chunk.midpoints  # {'x': <ndarray len=10>, 'y': <ndarray len=10>, 'DURATION': <ndarray len=10>}
+chunk.upper  # bounds are same dimensionality as positions
+```
+
+<!--
+Anything below this line is used when viewing README.md and will be replaced
+when included in index.md
+-->
+
+[plot]: https://raw.githubusercontent.com/dls-controls/scanspec/master/docs/images/plot_spec.png
+[logo]: https://raw.githubusercontent.com/dls-controls/scanspec/master/docs/images/scanspec-logo.svg
+
+See https://dls-controls.github.io/scanspec for more detailed documentation.

docs/conf.py

@@ -50,8 +50,13 @@
     "sphinx_copybutton",
     # For the card element
     "sphinx_design",
+    # So we can write markdown files
+    "myst_parser",
 ]
 
+# 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
@@ -106,9 +111,6 @@
 # role, that is, for text marked up `like this`
 default_role = "any"
 
-# The suffix of source filenames.
-source_suffix = ".rst"
-
 # The master toctree document.
 master_doc = "index"
 

docs/index.md

@@ -0,0 +1,54 @@
+```{include} ../README.md
+:end-before: when included in index.md
+```
+
+[plot]: images/plot_spec.png
+[logo]: images/scanspec-logo.svg
+
+How the documentation is structured
+-----------------------------------
+
+Documentation is split into four categories, also accessible from links in the
+side-bar.
+
+::::{grid} 2
+:gutter: 4
+
+:::{grid-item-card} {material-regular}`directions_walk;3em`
+:link: tutorials
+:link-type: doc
+
+Tutorials for installation and typical usage. New users start here.
+:::
+
+:::{grid-item-card} {material-regular}`directions;3em`
+:link: how-to
+:link-type: doc
+
+Practical step-by-step guides for the more experienced user.
+:::
+
+:::{grid-item-card} {material-regular}`info;3em`
+:link: explanations
+:link-type: doc
+
+Explanations of how it works and why it works that way.
+:::
+
+:::{grid-item-card} {material-regular}`menu_book;3em`
+:link: reference
+:link-type: doc
+
+Technical reference material including APIs and release notes.
+:::
+
+::::
+
+```{toctree}
+:hidden:
+
+tutorials
+how-to
+explanations
+reference
+```

pyproject.toml

@@ -21,7 +21,7 @@ dependencies = [
 ]
 dynamic = ["version"]
 license.file = "LICENSE"
-readme = "README.rst"
+readme = "README.md"
 requires-python = ">=3.8"
 
 [project.optional-dependencies]
@@ -55,6 +55,7 @@ dev = [
     "tox-direct",
     "types-mock",
     "httpx",
+    "myst-parser",
 ]
 
 [project.scripts]