refactor(docs): move from reST to Markdown (reanahub#65)

Convert docs from reStructuredText to Markdown so that the changelog file is compatible with Release Please.
mdonadoni · Feb 7, 2024 · e5bd869 · e5bd869
1 parent 8283064
commit e5bd869
Show file tree

Hide file tree

Showing 12 changed files with 141 additions and 169 deletions.
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -0,0 +1,10 @@
+# Authors
+
+The list of contributors in alphabetical order:
+
+- [Diego Rodriguez](https://orcid.org/0000-0003-0649-2002)
+- [Dinos Kousidis](https://orcid.org/0000-0002-4914-4289)
+- [Harri Hirvonsalo](https://orcid.org/0000-0002-5503-510X)
+- [Jan Okraska](https://orcid.org/0000-0002-1416-3244)
+- [Marco Donadoni](https://orcid.org/0000-0003-2922-5505)
+- [Tibor Simko](https://orcid.org/0000-0001-7202-5803)
diff --git a/AUTHORS.rst b/AUTHORS.rst
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.9.2 (2023-12-12)
+
+- Adds automated multi-platform container image building for amd64 and arm64 architectures.
+- Adds metadata labels to Dockerfile.
+
+## 0.9.1 (2023-09-27)
+
+- Fixes high memory usage of RabbitMQ by limiting the maximum number of open file descriptors.
+- Fixes container image names to be Podman-compatible.
+
+## 0.9.0 (2023-01-19)
+
+- Fixes documentation to set the default language to English.
+
+## 0.8.0 (2021-11-22)
+
+- Changes base image to the official RabbitMQ Docker image.
+- Adds RabbitMQ management UI exposed on port 31672 in the cluster debug mode.
+
+## 0.7.1 (2021-02-03)
+
+- Fixes minor code warnings.
+- Changes CI system to include Python flake8 and Dockerfile hadolint checkers.
+
+## 0.7.0 (2020-10-20)
+
+- Changes documentation to single-page layout.
+
+## 0.6.0 (2019-12-20)
+
+- Fixes documentation badge links.
+
+## 0.5.0 (2019-04-23)
+
+- Cleans REANA-Message-Broker Dockerfile by removing unused instructions.
+
+## 0.4.0 (2018-11-06)
+
+- Uses standardised REANA component documentation structure.
+- Changes license to MIT.
+
+## 0.2.0 (2018-04-19)
+
+- Adds dockerignore file to ease developments.
+
+## 0.1.0 (2018-01-30)
+
+- Initial public release.
+
diff --git a/CHANGES.rst b/CHANGES.rst
diff --git a/CONTRIBUTING.rst → CONTRIBUTING.md b/CONTRIBUTING.rst → CONTRIBUTING.md
@@ -1,20 +1,18 @@
-Contributing
-============
+# Contributing
 
 Bug reports, issues, feature requests, and other contributions are welcome. If you find
 a demonstrable problem that is caused by the REANA code, please:
 
-1. Search for `already reported problems
-   <https://github.com/reanahub/reana-message-broker/issues>`_.
+1. Search for [already reported problems](https://github.com/reanahub/reana-message-broker/issues).
 2. Check if the issue has been fixed or is still reproducible on the
    latest `master` branch.
 3. Create an issue, ideally with **a test case**.
 
 If you create a pull request fixing a bug or implementing a feature, you can run
 the tests to ensure that everything is operating correctly:
 
-.. code-block:: console
-
-    $ ./run-tests.sh
+```console
+$ ./run-tests.sh
+```
 
 Each pull request should preserve or increase code coverage.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -6,7 +6,6 @@
 
 include *.json
 include *.md
-include *.rst
 include *.sh
 include *.yaml
 include .dockerignore
@@ -17,6 +16,6 @@ include pytest.ini
 exclude .readthedocs.yaml
 recursive-include docs *.py
 recursive-include docs *.png
-recursive-include docs *.rst
+recursive-include docs *.md
 recursive-include docs *.txt
 recursive-include tests *.py
diff --git a/README.md b/README.md
@@ -0,0 +1,34 @@
+# REANA-Message-Broker
+
+[![image](https://github.com/reanahub/reana-message-broker/workflows/CI/badge.svg)](https://github.com/reanahub/reana-message-broker/actions)
+[![image](https://readthedocs.org/projects/reana-message-broker/badge/?version=latest)](https://reana-message-broker.readthedocs.io/en/latest/?badge=latest)
+[![image](https://codecov.io/gh/reanahub/reana-message-broker/branch/master/graph/badge.svg)](https://codecov.io/gh/reanahub/reana-message-broker)
+[![image](https://img.shields.io/badge/discourse-forum-blue.svg)](https://forum.reana.io)
+[![image](https://img.shields.io/github/license/reanahub/reana-message-broker.svg)](https://github.com/reanahub/reana-message-broker/blob/master/LICENSE)
+
+## About
+
+REANA-Message-Broker is a component of the [REANA](http://www.reana.io/) reusable and
+reproducible research data analysis platform. It provides a broker service for event
+messages and notifications.
+
+## Features
+
+- message queue for events
+- uses RabbitMQ
+
+## Usage
+
+The detailed information on how to install and use REANA can be found in
+[docs.reana.io](https://docs.reana.io).
+
+## Useful links
+
+- [REANA project home page](http://www.reana.io/)
+- [REANA user documentation](https://docs.reana.io)
+- [REANA user support forum](https://forum.reana.io)
+- [REANA-Message-Broker releases](https://reana-message-broker.readthedocs.io/en/latest#changes)
+- [REANA-Message-Broker docker images](https://hub.docker.com/r/reanahub/reana-message-broker)
+- [REANA-Message-Broker developer documentation](https://reana-message-broker.readthedocs.io/)
+- [REANA-Message-Broker known issues](https://github.com/reanahub/reana-message-broker/issues)
+- [REANA-Message-Broker source code](https://github.com/reanahub/reana-message-broker)
diff --git a/README.rst b/README.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -34,6 +34,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
     "sphinx.ext.doctest",
@@ -49,14 +50,17 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
+
+# Allow using ::: in Markdown files
+myst_enable_extensions = ["colon_fence"]
 
 # The master toctree document.
 master_doc = "index"
 
 # General information about the project.
 project = "reana"
-copyright = "2017-2023, [email protected]"
+copyright = "2017-2024, [email protected]"
 author = "[email protected]"
 
 # The version info for the project you're documenting, acts as replacement for

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,30 @@
+```{include} ../README.md
+:end-before: "## About"
+```
+
+```{include} ../README.md
+:start-after: "## About"
+:end-before: "## Useful links"
+```
+
+```{include} ../CHANGELOG.md
+:heading-offset: 1
+```
+
+```{include} ../CONTRIBUTING.md
+:heading-offset: 1
+```
+
+## License
+
+```{eval-rst}
+.. include:: ../LICENSE
+```
+
+In applying this license, CERN does not waive the privileges and immunities
+granted to it by virtue of its status as an Intergovernmental Organization or
+submit itself to any jurisdiction.
+
+```{include} ../AUTHORS.md
+:heading-offset: 1
+```
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/setup.py b/setup.py
@@ -15,8 +15,8 @@
 
 from setuptools import find_packages, setup
 
-readme = open("README.rst").read()
-history = open("CHANGES.rst").read()
+readme = open("README.md").read()
+history = open("CHANGELOG.md").read()
 
 tests_require = [
     "check-manifest>=0.25",
@@ -30,6 +30,7 @@
 
 extras_require = {
     "docs": [
+        "myst-parser",
         "Sphinx>=1.4.4",
         "sphinx-rtd-theme>=0.1.9",
     ],
@@ -60,6 +61,7 @@
     version=version,
     description=__doc__,
     long_description=readme + "\n\n" + history,
+    long_description_content_type="text/markdown",
     author="REANA",
     author_email="[email protected]",
     url="https://github.com/reanahub/reana-message-broker",