rearranged tutorials. Added intro to tutorials and quick start
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/b02507e1 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/b02507e1 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/b02507e1 Branch: refs/heads/master Commit: b02507e1f29f9cad4c6e01b2227ce8e9837a0d62 Parents: 46aa285 Author: aditihilbert <ad...@runtime.io> Authored: Thu Mar 17 16:35:38 2016 -0700 Committer: aditihilbert <ad...@runtime.io> Committed: Thu Mar 17 16:35:38 2016 -0700 ---------------------------------------------------------------------- docs/os/core_os/mutex/mutex.md | 2 +- docs/os/get_started/get_started.md | 12 ++++ docs/os/tutorials/how_to_edit_docs.md | 104 ++++------------------------- docs/os/tutorials/tutorials.md | 16 +++++ docs/os/tutorials/unit_test.md | 2 +- mkdocs.yml | 8 ++- 6 files changed, 48 insertions(+), 96 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b02507e1/docs/os/core_os/mutex/mutex.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mutex/mutex.md b/docs/os/core_os/mutex/mutex.md index ce123ca..c397aa4 100644 --- a/docs/os/core_os/mutex/mutex.md +++ b/docs/os/core_os/mutex/mutex.md @@ -16,7 +16,7 @@ Note that when multiple tasks are waiting on a mutex owned by another task, once ### Data structures -```c +```c struct os_mutex { SLIST_HEAD(, os_task) mu_head; http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b02507e1/docs/os/get_started/get_started.md ---------------------------------------------------------------------- diff --git a/docs/os/get_started/get_started.md b/docs/os/get_started/get_started.md new file mode 100644 index 0000000..0f45918 --- /dev/null +++ b/docs/os/get_started/get_started.md @@ -0,0 +1,12 @@ +## Quick Start + +If you are curious about Mynewt and want to get a quick feel for the project, you've come to the right place. We have three sets of instructions for you to try out. + +* [Installing Native Tools](native_tools.md) - to run Mynewt OS natively (on your machine) +* [Creating Your First Project](project_create.md) - on simulated hardware +* [Installing Cross Tools for ARM](cross_tools.md) - to get prepared to play with hardware + +**Send us an email on the dev@ mailing list if you have comments or suggestions!** If you haven't joined the mailing list, you will find the links [here](../../community.md). + +<br> + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b02507e1/docs/os/tutorials/how_to_edit_docs.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/how_to_edit_docs.md b/docs/os/tutorials/how_to_edit_docs.md index d1cb3e5..b3229c6 100644 --- a/docs/os/tutorials/how_to_edit_docs.md +++ b/docs/os/tutorials/how_to_edit_docs.md @@ -8,9 +8,7 @@ Learn the process of editing docs by adding some content to a test document. The Mynewt documentation you see on the Apache incubator website is a bunch of HTML files generated using MkDocs which is a simple static site generation tool geared towards building project documentation. You can read about it at [http://www.mkdocs.org](http://www.mkdocs.org). Documentation source files are written in Markdown, and configured with a single YAML configuration file. Markdown is a lightweight markup language with plain text formatting syntax designed so that it can be converted to HTML and many other formats using a tool (which in our case is MkDocs). -You do not need to install MkDocs unless you want to actually render your documentation in HTML in order to preview it before pushing your content to the remote repository. Typically, using a Markdown editor such as [Mou](http://25.io/mou/) is enough to check how it will look after the document has gone through MkDocs. Go ahead and download [Mou](http://25.io/mou/). If you are on a Windows machine, download the [editor of your choice](http://alternativeto.net/software/mou/?platform=windows). - -Currently someone in the project is designated to use MkDocs to generate the HTML pages periodically after changes have been reviewed and accepted into the master branch. +The HTML pages are generated periodically after changes have been reviewed and accepted into the master branch. ### Access to the Apache repo @@ -19,104 +17,28 @@ Get an account on Apache. You do not need a committer account to view the websit If you are not a committer, you may follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is [https://git-wip-us.apache.org/docs/workflow.html](https://git-wip-us.apache.org/docs/workflow.html). You will find the steps described in more detail later in this tutorial. -### Making a local copy - -* Copy the document source files into a local directory and look at the contents of the copied directory to get an idea of the directory structure. Use http instead of https if you are a non-committer. -```c - $ git clone https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git - Cloning into 'incubator-mynewt-site'... - remote: Counting objects: 330, done. - remote: Compressing objects: 100% (263/263), done. - remote: Total 330 (delta 120), reused 0 (delta 0) - Receiving objects: 100% (330/330), 4.34 MiB | 830.00 KiB/s, done. - Resolving deltas: 100% (120/120), done. - Checking connectivity... done. - $ ls - incubator-mynewt-site - $ ls incubator-mynewt-site/ - docs images mkdocs.yml +### Editing an existing page + +* Create a fork on the [github mirror](https://github.com/apache/incubator-mynewt-site). +* +* Then create a new branch to work on your documentation and move to that branch. ``` -* Create a new branch to work on your documentation and move to that branch. -```c $ git checkout -b <your-branch-name> ``` -### File to be edited - -The file you will edit is named try_markdown.md. It is in the incubator-mynewt-site/docs/os/tutorials/ directory. - -### Editing an existing page - -* Open the application Mou. - -* Open the file incubator-mynewt-site/docs/os/tutorials/try_markdown.md in Mou. - -* Edit the last item on the list. - -* Save and quit the application. +* Make changes directly on github.com. Generate a pull request. Alternatively, you can edit locally on your machine, push the branch (or the changes in the branch) to your fork on github.com, and then generate a pull request. ### Adding a new page -If you create a new file somewhere in the `docs` subdirectory to add a new page, you have to add a line in the `mkdocs.yml` file at the correct level. For example, if you add a new module named "Ethernet" by creating a new file named `ethernet.md` in the `modules` subdirectory, you have to insert the following line under `Modules:` in the `mkdocs.yml` file. -```c - - 'Ethernet': 'modules/ethernet.md' -``` -### Pushing changes to remote as a committer +If you create a new file somewhere in the `docs` subdirectory to add a new page, you have to add a line in the `mkdocs.yml` file at the correct level. For example, if you add a new module named "Wi-Fi" by creating a new file named `wifi.md` in the `network` directory, you have to insert the following line under `Networking User Guide` in the `mkdocs.yml` file (at the same level as the `docs` directory). In this example, a link will show up in the navigation bar on the left under "Networking User Guide" titled "Wi-Fi" and take the user to the contents of the 'wifi.md' file when the link is clicked. ** Note: The change will show up on this [Mynewt site](http://mynewt.apache.org) only after your pull request is merged in and the updated site is generated.** -If you are not a committer yet, skip this section and proceed to the [next section](#sharing-changes-as-a-non-committer). - -* Check whether your remote git repository is set up. If you see the remote location as shown below you can skip the next step. -```c - $ git remote -v - origin https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git (fetch) - origin https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git (push) ``` -* If, however, you do not see your remote repository, then set it up as follows. - -```c - $ git remote add origin https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git -``` -* First check the git status. It will show you that the `try_markdown.md` document has been modified. So you will stage a commit, and then commit the change. Finally, you will push the changes to the remote repository. - - During staging below using `git add`, we use the `-A` option indicating you want to stage all your modifications. Instead, you can choose to specify only the files that you want to. The commit message (specified after `-m`) should summarize what your changes are about. -```c - $ git status - $ git add -A - $ git commit -m "My first doc change as a trial run" - $ git push -u origin <your-branch-name> -``` -* You can see the changed Markdown file if you traverse the tree on the git repository [ https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git]( https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git). - -* A commit notification automatically goes out to the commits@mynewt.incubator.apache.org mailing list. The "upstream" manager pulls the notified changes, reviews it, and merges it to the master branch if all is well. Otherwise you get an email for further changes. - -### Sharing changes as a non-committer - -We suggest you follow the proposed non-committer workflow at Apache to share your work. The direct link to the proposed workflow is [https://git-wip-us.apache.org/docs/workflow.html](https://git-wip-us.apache.org/docs/workflow.html). - -* Assuming you have made changes to the example file, you will first commit your changes. -```c - $ git add -A - $ git commit -m "My first doc change as a trial run" + - 'Wi-Fi': 'wifi.md' ``` -* Once you're ready to share your changes with the rest of the project team, you can use the git format-patch command to produce a patch file (or a nice set of patches in the future) and email the patch file to d...@mynewt.incubator.apache.org. Later on you may attach multiple files in your email to the mailing list as part of an existing thread or a new one. Remember to summarize the issue you have tackled and your work if the commit message is not detailed enough. - - If there is a JIRA ticket associated with your work you should post your patch files to the ticket. - -```c - $ git format-patch origin/trunk -``` - -* Alternatively, you can use the mirror on github.com to submit a pull request. The mirror is located at [https://github.com/apache/incubator-mynewt-site](https://github.com/apache/incubator-mynewt-site). It is up to you to decide whether to create a fork or a branch to work in and submit pull requests from. Remember you cannot push changes to the master on the github mirror, so you have to create a fork or a branch first. Your pull request will be reviewed by a committer for docs and merged into the master branch when the changes are understood and accepted. - - -### Conversion to HTML - -The conversion of the Markdown files to HTML for the website happens manually and statically using MkDocs. You cannot see automatic and immediate rendering in HTML upon making a change in the Markdown file. You can choose to stop here and proceed to changing other Markdown files in your branch. - ### Local preview of HTML files -However, you have the option to download MkDocs and do a local conversion yourself to preview the pages using the built-in devserver that comes with MkDocs. But first you will have to install MkDocs for that. In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have them already (usually you will). -```c +You have the option to install MkDocs and do a local conversion yourself to preview the pages using the built-in webserver that comes with MkDocs. In order to install MkDocs you'll need Python installed on your system, as well as the Python package manager, pip. You can check if you have them already (usually you will). +``` $ python --version Python 2.7.2 $ pip --version @@ -124,11 +46,11 @@ However, you have the option to download MkDocs and do a local conversion yourse $ pip install mkdocs ``` You will then run the built-in webserver from the root of the documentation directory using the command `mkdocs serve`. The root directory for documentation is `incubator-mynewt-site` or the directory with the `mkdocs.yml` file. -```c +``` $ ls docs images mkdocs.yml $ mkdocs serve ``` -Then go to [http://127.0.0.1:8000](http://127.0.0.1:8000) to preview your pages and see how they will look on the website! Remember that the Myself website itself will not be updated. +Then go to [http://127.0.0.1:8000](http://127.0.0.1:8000) to preview your pages and see how they will look on the website. **Remember that the Myself website itself will not be updated.** For more information on MkDocs go to [http://www.mkdocs.org](http://www.mkdocs.org). http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b02507e1/docs/os/tutorials/tutorials.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/tutorials.md b/docs/os/tutorials/tutorials.md new file mode 100644 index 0000000..2e57243 --- /dev/null +++ b/docs/os/tutorials/tutorials.md @@ -0,0 +1,16 @@ +## Tutorials + +If the introduction to Mynewt has piqued your interest and you want to familiarize yourself with some of its functionality, this series of tutorials is for you. The lessons are aimed at the beginner. + +* [Blinky on Arduino Zero hardware](arduino_zero.md) +* [Blinky on Olimex/STM32F407ZGT6 Cortex-M4 hardware](olimex.md) +* [Blinky on STM32F3 discovery kit from ST Micro](STM32F303.md) +* [Blinky on nRF52 Development Kit from Nordic Semiconductor](nRF52.md) **Note:** This supports BLE. +* [Add a unit Test for a Package](unit_test.md) +* [Add an air-quality sensor](air_quality_sensor.md) +* [How to contribute to docs](how_to_edit_docs.md) + +**Send us an email on the dev@ mailing list if you have comments or suggestions!** If you haven't joined the mailing list, you will find the links [here](../../community.md). + +<br> + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b02507e1/docs/os/tutorials/unit_test.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/unit_test.md b/docs/os/tutorials/unit_test.md index 985085f..c94f819 100644 --- a/docs/os/tutorials/unit_test.md +++ b/docs/os/tutorials/unit_test.md @@ -1,4 +1,4 @@ -# How To Write A Test Suite for Your Package +# Write a Test Suite for a Package This document presents a tutorial which guides the reader through writing a test suite for a Mynewt package (new or existing). http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/b02507e1/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index e680744..f1e0a71 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,18 +13,20 @@ pages: - Mynewt OS Manual: - Introduction: 'os/get_started/introduction.md' - Get Started: + - toc: 'os/get_started/get_started.md' - 'Installing Native Tools': 'os/get_started/native_tools.md' - 'Creating Your First Project': 'os/get_started/project_create.md' - 'Installing Cross Tools for ARM': 'os/get_started/cross_tools.md' - 'Concepts': - toc: 'os/get_started/vocabulary.md' - Tutorials: + - toc: 'os/tutorials/tutorials.md' + - 'Blinky on Arduino Zero': 'os/tutorials/arduino_zero.md' - 'Blinky on Olimex': 'os/tutorials/olimex.md' - 'Blinky on STM32F303': 'os/tutorials/STM32F303.md' - 'Blinky on nRF52': 'os/tutorials/nRF52.md' - - 'Blinky on Arduino Zero': 'os/tutorials/arduino_zero.md' - - 'Unit Testing a Package': 'os/tutorials/unit_test.md' - - 'Adding an air-quality sensor': 'os/tutorials/air_quality_sensor.md' + - 'Write a Test Suite for a Package': 'os/tutorials/unit_test.md' + - 'Air-quality Sensor project': 'os/tutorials/air_quality_sensor.md' - 'Edit Docs': 'os/tutorials/how_to_edit_docs.md' - OS User Guide: - OS Core:
