This is an automated email from the ASF dual-hosted git repository.
janc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-documentation.git
The following commit(s) were added to refs/heads/master by this push:
new 00ec3b8 README: fix Markdown syntax
00ec3b8 is described below
commit 00ec3b806b7ea1fb1c9faef75f4abfec05b6dfc6
Author: Wojciech Pietraszewski <[email protected]>
AuthorDate: Fri May 10 17:54:40 2024 +0200
README: fix Markdown syntax
Changes the syntax from .rst to .md
---
README.md | 141 ++++++++++++++++++++++++++++----------------------------------
1 file changed, 63 insertions(+), 78 deletions(-)
diff --git a/README.md b/README.md
index 9c4b216..f85dbb0 100644
--- a/README.md
+++ b/README.md
@@ -1,114 +1,108 @@
-Apache Mynewt Documentation
-###########################
+# Apache Mynewt Documentation
-.. contents::
+### Contents
+ * [Writing Documentation](#writing-documentation)
+ * [Preview Changes](#preview-changes)
+ * [Setup (macOS)](#setup-macos)
+ * [Prerequisites](#prerequisites)
+ * [Toolchain Install](#toolchain-install)
+ * [Setup (Linux)](#setup-linux)
+ * [Deploying the latest docs](#deploying-the-latest-docs)
+ * [Creating a versioned set of docs](#creating-a-versioned-set-of-docs)
-This is the project documentation for the `Apache Mynewt`_ project. It is
built using `Sphinx`_.
+This is the project documentation for the [Apache
Mynewt](https://mynewt.apache.org/) project. It is built using
[Sphinx](https://www.sphinx-doc.org/).
-Each component of Mynewt contains its own specific documentation in its repo
under ``docs``. At
+Each component of Mynewt contains its own specific documentation in its repo
under `docs`. At
build time these are combined to create the full document set for publication.
-The `Apache Mynewt`_ source code also contains inline comments in `Doxygen`_
format to document its APIs.
+The [Apache Mynewt](https://mynewt.apache.org/) source code also contains
inline comments in [Doxygen](https://www.doxygen.nl/) format to document its
APIs.
-Writing Documentation
-=======================
+## Writing Documentation
-`Sphinx`_ use reStructuredText. http://www.sphinx-doc.org/en/stable/rest.html.
+[Sphinx](https://www.sphinx-doc.org/) uses
[reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html).
-Embedding `Doxygen`_ generated source documentation is through the `Breathe`_
-bridge. http://breathe.readthedocs.io/en/latest/. This bridge embeds source
-documentation using `Sphinx`_'s C domain. For example:
-``.. doxygenfile:: full/include/console/console.h``
+Embedding [Doxygen](https://www.doxygen.nl/) generated source documentation is
through the [Breathe](https://breathe.readthedocs.io/)
+bridge. This bridge embeds source
+documentation using [Sphinx](https://www.sphinx-doc.org/)'s C domain. For
example:
+`.. doxygenfile:: full/include/console/console.h`
-Documents can then refer to code elements using the C domain syntax:
-http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs
-For example: ``:c:func:`console_read()``` or ``:c:data:`console_input```.
+Documents can then refer to code elements using the [C domain
syntax](https://www.sphinx-doc.org/en/master/usage/domains/c.html#cross-referencing-c-constructs).
+For example: `` :c:func:`console_read()` `` or `` :c:data:`console_input` ``.
Linking to other files should be relative for ease of deployment and
multi-version
-support. For example ``:doc:`../../newt/install/newt_mac```.
+support. For example `` :doc: `../../newt/install/newt_mac` ``.
-Preview Changes
-=================
+## Preview Changes
-``make clean && make docs && (cd _build/html && python -m SimpleHTTPServer
8080)``
+`make clean && make docs && (cd _build/html && python -m SimpleHTTPServer
8080)`
-Setup (MacOS)
-===============
+## Setup (macOS)
-Note: This build toolchain is known to work on MacOS 10.11.
+Note: This build toolchain is known to work on macOS 10.11.
-Prerequisites:
-***************
+### Prerequisites
-* `homebrew`_
-
-.. code-block:: bash
+* [Homebrew](https://brew.sh/)
+```bash
$ brew --version
Homebrew 1.1.7
-
+```
* python
-.. code-block:: bash
-
+```bash
$ python --version
Python 2.7.10
+```
+* [pip](https://pip.pypa.io/en/stable/installation/)
-* `pip`_
-
-.. code-block:: bash
-
- $ pip --version
- pip 9.0.1 from /Library/Python/2.7/site-packages (python 2.7)
-
-
-Toolchain Install:
-*******************
+```bash
+$ pip --version
+pip 9.0.1 from /Library/Python/2.7/site-packages (python 2.7)
+```
-.. code-block:: bash
+### Toolchain Install
- $ git clone https://github.com/sphinx-doc/sphinx.git sphinx
+```bash
+$ git clone https://github.com/sphinx-doc/sphinx.git sphinx
- $ cd sphinx && sudo -E python setup.py install && cd ..
+$ cd sphinx && sudo -E python setup.py install && cd ..
- $ git clone https://github.com/michaeljones/breathe.git breathe
+$ git clone https://github.com/michaeljones/breathe.git breathe
- $ cd breathe && sudo -E python setup.py install && cd ..
+$ cd breathe && sudo -E python setup.py install && cd ..
- $ brew install doxygen
+$ brew install doxygen
- $ sudo pip install recommonmark
-
-Setup (Linux)
-===============
+$ sudo pip install recommonmark
+```
+## Setup (Linux)
Most Linux distributions provide necessary packages in their repositories.
Ubuntu/Debian
-.. code-block:: bash
-
- sudo apt-get install doxygen python3-breathe python3-recommonmark
-
+```bash
+sudo apt-get install doxygen python3-breathe python3-recommonmark
+```
Fedora
-.. code-block:: bash
- sudo dnf install doxygen python3-breathe python3-recommonmark
+```bash
+sudo dnf install doxygen python3-breathe python3-recommonmark
+```
-Deploying the latest docs
-=========================
+## Deploying the latest docs
NOTE: These instructions assume that your workspace has all the mynewt repos
cloned under the same parent directory.
-* Ensure that all changes are merged into ``master`` and that the ``master``
+* Ensure that all changes are merged into `master` and that the `master`
branch is checked out.
* Repeat for any mynewt code repo that has documentation changes.
-* Follow the steps at `Site Docs`_ to release the docs.
+* Follow the steps at [Site
Docs](https://github.com/apache/mynewt-site#deploying-the-latest-docs) to
release the docs.
-Creating a versioned set of docs
-================================
+## Creating a versioned set of docs
-When the master/latest documentation is deemed representative of a Mynewt
+When the `master`/`latest` documentation is deemed representative of a Mynewt
version, it is time to create a versioned set.
* Make sure all your mynewt-* repos are up to date and that all changes are
@@ -116,7 +110,7 @@ version, it is time to create a versioned set.
* Add the new version to mynewt-documentation/docs/themes/mynewt/versions.html
* Also add the new version to any existing archived set.
- * i.e
``mynewt-documentation/versions/*/mynewt-documentation/docs/themes/mynewt/versions.html``
+ * i.e
`mynewt-documentation/versions/*/mynewt-documentation/docs/themes/mynewt/versions.html`
* Make sure the 'selected' flag is correct for the archived version
* Make a versions/vX_Y_Z directory
@@ -125,8 +119,8 @@ version, it is time to create a versioned set.
* Repeat for other mynewt-* repos with doxygen docs and a /docs folder
* Update the version fields in
- * ``docs/conf.py``
- * and ``versions/vX_Y_Z/mynewt-documentation/docs/conf.py``
+ * `docs/conf.py`
+ * and `versions/vX_Y_Z/mynewt-documentation/docs/conf.py`
* Add a warning that this is not the most recent documentation to:
@@ -134,16 +128,7 @@ version, it is time to create a versioned set.
* see an existing older version for example
To preview the changes:
-
-.. code-block:: bash
-
+```bash
cd mynewt-documentation/versions/vX_Y_Z/mynewt-documentation
make clean && make docs && (cd _build/html && python -m SimpleHTTPServer
8080)
-
-.. _Apache Mynewt: https://mynewt.apache.org/
-.. _Sphinx: http://www.sphinx-doc.org/
-.. _Doxygen: http://www.doxygen.org/
-.. _Homebrew: http://brew.sh/
-.. _Pip: https://pip.readthedocs.io/en/stable/installing/
-.. _Breathe: http://breathe.readthedocs.io/en/latest/
-.. _Site Docs: https://github.com/apache/mynewt-site#deploying-the-latest-docs
+```
