You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/01/06 22:56:13 UTC
[10/45] incubator-mynewt-site git commit: updated instructions on
editing docs
updated instructions on editing docs
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/57023d13
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/57023d13
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/57023d13
Branch: refs/heads/asf-site
Commit: 57023d1398c66a681443615d5e9d8834f03895c6
Parents: 1c43668
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Nov 19 16:38:54 2015 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Thu Nov 19 16:38:54 2015 -0800
----------------------------------------------------------------------
docs/chapter1/how_to_edit_docs.md | 107 ++++++++++++++++++++++++++++++---
docs/chapter1/project1.md | 40 +++++++-----
docs/chapter1/try_markdown.md | 13 +++-
docs/index.md | 6 +-
mkdocs.yml | 12 ++--
5 files changed, 147 insertions(+), 31 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/57023d13/docs/chapter1/how_to_edit_docs.md
----------------------------------------------------------------------
diff --git a/docs/chapter1/how_to_edit_docs.md b/docs/chapter1/how_to_edit_docs.md
index 10238b6..f3da5cf 100644
--- a/docs/chapter1/how_to_edit_docs.md
+++ b/docs/chapter1/how_to_edit_docs.md
@@ -8,9 +8,16 @@ We will go through the process of downloading existing doccumentation and adding
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 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).
+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.
+
+
+### Access to the Apache repo
+
+
+Get an account on Apache. You do not need an account to view the website or clone the repository but you need it to push changes to it.
-Currently someone in the project is designated to use MkDocs to generate the HTML pages periodically after changes have been reviewed and accepted by the group.
### Making a local copy
@@ -48,6 +55,61 @@ The file you will edit is [try_markdown.md](./try_markdown.md).
* Save and quit the application.
+You may want to review the documentation organization back in [Home](../index.md) to remind you how to locate files easily. The corresponding directory tree structure is shown below.
+
+ .
+ ├── docs
+ │ ├── chapter1
+ │ │ ├── how_to_edit_docs.md
+ │ │ ├── newt_concepts.md
+ │ │ ├── pics
+ │ │ │ ├── bottomview.png
+ │ │ │ └── topview.png
+ │ │ ├── project1.md
+ │ │ └── try_markdown.md
+ │ ├── chapter2
+ │ │ ├── project2.md
+ │ │ ├── project3.md
+ │ │ ├── ... (more to be added)
+ │ │ └── vocabulary.md
+ │ ├── chapter3
+ │ │ ├── newt_ops.md
+ │ │ └── newt_tool_reference.md
+ │ ├── chapter4
+ │ │ ├── context_switch.md
+ │ │ ├── event_queue.md
+ │ │ ├── heap.md
+ │ │ ├── mbufs.md
+ │ │ ├── memory_pool.md
+ │ │ ├── mutex.md
+ │ │ ├── mynewt_os.md
+ │ │ ├── port_os.md
+ │ │ ├── sanity.md
+ │ │ ├── semaphore.md
+ │ │ ├── task.md
+ │ │ ├── time.md
+ │ │ └── ... (more to be added)
+ │ ├── chapter5
+ │ │ ├── bootloader.md
+ │ │ ├── console.md
+ │ │ ├── filesystem.md
+ │ │ ├── shell.md
+ │ │ ├── testutil.md
+ │ │ └── ... (more to be added)
+ │ ├── chapter6
+ │ │ ├── dist.md
+ │ │ └── ... (more to be added)
+ │ ├── extra.css
+ │ ├── images
+ │ │ └── egg-logo.png
+ │ └── index.md
+ ├── images
+ │ ├── asf_logo_wide.gif
+ │ ├── content-bg.png
+ │ └── egg-logo.png
+ ├── mkdocs.yml
+
+
### 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 chapter5 subdirectory, you have to insert the following line under `Modules:` in the `mkdocs.yml` file.
@@ -56,17 +118,48 @@ If you create a new file somewhere in the `docs` subdirectory to add a new page,
### Pushing changes to remote
-* Set up your remote git repository
+* Check whether your remote git repository is set up.
- $ git remote add origin https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git
$ 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)
-
-* Commit and push the changes to the remote repository.
+
+* If it is not, set it up. Otherwise, proceed to the next step.
+
+
+ $ git remote add origin https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git
+
+* Commit and push the changes to the remote repository. Instead of "Green Arrow" type in your username.
$ git add -A
$ git commit -m "Green Arrow's first doc change"
$ git push -u origin <your-branch-name>
-
\ No newline at end of file
+* 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.
+
+
+### 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).
+
+ $ python --version
+ Python 2.7.2
+ $ pip --version
+ pip 1.5.2
+ $ 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.
+
+ $ 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.
+
+For more information on MkDocs go to [http://www.mkdocs.org].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/57023d13/docs/chapter1/project1.md
----------------------------------------------------------------------
diff --git a/docs/chapter1/project1.md b/docs/chapter1/project1.md
index cff85f1..6ae00a5 100644
--- a/docs/chapter1/project1.md
+++ b/docs/chapter1/project1.md
@@ -8,9 +8,12 @@ We will show you how you can use eggs from a nest on Mynewt to make an LED on a
2. Second, we will walk you through a download of eggs for building and testing [on a simulated target](#building-test-code-on-simulator) on a non-Windows machine.
3. Third, you will download eggs and use tools to create a runtime image for a board to make its LED blink. You have two choices here - you can [download an image to SRAM](#making-an-led-blink-from-sram) or you can [download it to flash](#using-flash-to-make-led-blink).
+** Time Requirement**: Allow yourself a couple of hours for this project if you are relatively new to embedded systems and playing with development boards. Those jumpers can be pesky!
+
+
### What you need
-1. STM32-E407 development board from Olimex.
+1. STM32-E407 development board from Olimex. You can order it from [http://www.mouser.com](http://www.mouser.com/ProductDetail/Olimex-Ltd/STM32-E407/?qs=UN6GZl1KCcit6Ye0xmPO4A%3D%3D), [http://www.digikey.com](http://www.digikey.com/product-detail/en/STM32-E407/1188-1093-ND/3726951), and other places.
2. ARM-USB-TINY-H connector with JTAG interface for debugging ARM microcontrollers (comes with the ribbon cable to hook up to the board)
3. USB A-B type cable to connect the debugger to your personal computer
4. Personal Computer
@@ -59,20 +62,23 @@ case, simply skip the corresponding installation step in the instructions under
$ cd dev/go
$ export GOPATH=`pwd`
- Note that you need to add export statements to ~/.bash_profile to export variables permanently.
+ Note that you need to add export statements to ~/.bash_profile to export variables permanently. Don't forget to source the file for the change to go into effect.
+
$ vi ~/.bash_profile
+ $ source ~/.bash_profile
-* Next you will use brew to install go. The summary message at the end of the installation should indicate that it is installed in the /usr/local/Cellar/go/ directory. You will use the go command 'install' to compile and install packages (called eggs in the Mynewt world) and dependencies.
+* Next you will use brew to install Go. The summary message at the end of the installation should indicate that it is installed in the /usr/local/Cellar/go/ directory. You will use the Go command 'install' to compile and install packages (called eggs in the Mynewt world) and dependencies.
$ brew install go
==>
- ==>
+ ...
+ ...
==> *Summary*
🍺 /usr/local/Cellar/go/1.5.1: 5330 files, 273M
- Alternatively, you can download the go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory.
+ Alternatively, you can download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory.
-* You will now get the godep package. Make sure you are at the go directory level and get godep. Check for it in the bin subdirectory. Add the go environment to path. Make sure it is added to your .bash_profile.
+* You will now get the godep package. Make sure you are at the Go directory level and get godep. Check for it in the bin subdirectory. Add the Go environment to path. Make sure it is added to your .bash_profile.
$ cd $GOPATH
$ go get github.com/tools/godep
@@ -82,7 +88,7 @@ case, simply skip the corresponding installation step in the instructions under
#### Creating local repository
-* You are ready to download the newt tool repository. You will use "go" to copy the directory (currently the asf incubator directory). Be patient as it may take a minute or two. Check the directories installed.
+* You are ready to download the newt tool repository. You will use Go to copy the directory (currently the asf incubator directory). Be patient as it may take a minute or two. Check the directories installed.
$ go get git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git
$ $ ls
@@ -93,14 +99,16 @@ case, simply skip the corresponding installation step in the instructions under
* Check that newt is installed.
- $ ls $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/mkdir -p $GOPATH/src/github.com/mynewt
+ $ ls $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git
Godeps README.md coding_style.txt newt.go
LICENSE cli design.txt
#### Building the Newt tool
-* You will now use go to run the newt.go program to build the newt tool. You will have to use `go build` command which compiles and writes the resulting executable to an output file named `newt`. The `-o` option is used to specify a reasonable name such as `newt` for the the resulting executable and install the executable along with its dependencies in $GOPATH/bin. In preparation for the install, you may use the godep command 'restore' to check out listed dependency versions in $GOPATH and link all the necessary files.
+* In preparation for the install, you use the godep command 'restore' to check out listed dependency versions in $GOPATH and link all the necessary files.
+
+ You will use Go to run the newt.go program to build the newt tool. The command used is `go build` which compiles and writes the resulting executable to an output file named `newt`. The `-o` option is used to specify a name and path of your choice for the executable. We suggest using `newt` and installing the executable along with its dependencies in $GOPATH/bin.
However, it does not install the results along with its dependencies in $GOPATH/bin (for that you will need to use `go install`).
@@ -181,7 +189,7 @@ case, simply skip the corresponding installation step in the instructions under
Note: If no version is specified, brew will install the latest version available. MynewtOS will eventually work with multiple versions available including the latest releases. However, at present we have tested only with this version and recommend it for getting started.
-* You have to install OpenOCD (Open On-Chip Debugger) which is an open-source software that will allow you to interface with the JTAG debug connector/adaptor for the Olimex board. It lets you program, debug, and test embedded target devices which, in this case, is the Olimex board. Use brew to install it. Brew adds a simlink /usr/local/bin/openocd to the openocd directory in the Cellar.
+* You have to install OpenOCD (Open On-Chip Debugger) which is an open-source software that will allow you to interface with the JTAG debug connector/adaptor for the Olimex board. It lets you program, debug, and test embedded target devices which, in this case, is the Olimex board. Use brew to install it. Brew adds a simlink /usr/local/bin/openocd to the openocd directory in the Cellar. For more on OpenOCD go to [http://openocd.org](http://openocd.org).
$ brew install open-ocd
$ which openocd
@@ -200,7 +208,7 @@ case, simply skip the corresponding installation step in the instructions under
#### Installing some prerequisites
-* Install git, libcurl, and the go language if you do not have them already.
+* Install git, libcurl, and the Go language if you do not have them already.
$ sudo apt-get install git
$ sudo apt-get install libcurl4-gnutls-dev
@@ -233,7 +241,7 @@ case, simply skip the corresponding installation step in the instructions under
#### Building the newt tool
-* You will now use go to run the newt.go program to build the newt tool. You will have to use `go build` command which compiles and writes the resulting executable to an output file named `newt`. The `-o` option is used to specify a reasonable name such as `newt` for the the resulting executable and install the executable along with its dependencies in $GOPATH/bin. In preparation for the install, you may use the godep command 'restore' to check out listed dependency versions in $GOPATH and link all the necessary files.
+* You will now use Go to run the newt.go program to build the newt tool. You will have to use `go build` command which compiles and writes the resulting executable to an output file named `newt`. The `-o` option is used to specify a reasonable name such as `newt` for the the resulting executable and install the executable along with its dependencies in $GOPATH/bin. In preparation for the install, you may use the godep command 'restore' to check out listed dependency versions in $GOPATH and link all the necessary files.
$ ~/dev/go/bin/godep restore
$ go build -o "$GOPATH"/bin/newt
@@ -425,7 +433,7 @@ tutorial for a Windows machine assumes the specified folders.
Godeps README.md coding_style.txt newt.go
LICENSE cli design.txt
-* Use the go command 'install' to compile and install packages and dependencies. Add go environment to path. Again, to make the export variable permanent, add it to your ~/.bashrc (or equivalent) file.
+* Use the Go command 'install' to compile and install packages and dependencies. Add Go environment to path. Again, to make the export variable permanent, add it to your ~/.bashrc (or equivalent) file.
$ %GOPATH%\bin\godep restore
$ go get
@@ -433,7 +441,7 @@ tutorial for a Windows machine assumes the specified folders.
#### Building the newt tool
-* You will now use go to run the newt.go program to build the newt tool. You will have to use `go build` command which compiles and writes the resulting executable to an output file named `newt`. However, it does not install the results along with its dependencies in $GOPATH/bin (for that you will need to use `go install`). Now try running newt using the compiled binary. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'.
+* You will now use Go to run the newt.go program to build the newt tool. You will have to use `go build` command which compiles and writes the resulting executable to an output file named `newt`. However, it does not install the results along with its dependencies in $GOPATH/bin (for that you will need to use `go install`). Now try running newt using the compiled binary. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'.
Note: If you are going to be be modifying the newt tool itself often and wish to compile the program every time you call it, you may want to define the newt environment variable that allows you to execute the command via `%newt%`. Use `set newt=go run %GOPATH%\src\github.com\mynewt\newt\newt.go` or set it from the GUI. Here, you use `go run` which runs the compiled binary directly without producing an executable.
@@ -608,6 +616,8 @@ Coming soon.
### Making an LED blink from SRAM
+You are here because you want to build an image to be run from internal SRAM on the Olimex board.
+
#### Preparing the Software
1. Make sure the PATH environment variable includes the $HOME/dev/go/bin directory (or C:\%GOPATH%\bin on Windows machine).
@@ -769,6 +779,8 @@ Coming soon.
### Using flash to make LED blink
+You are here because you want to build an image to be run from flash memory on the Olimex board.
+
1. Configure the board to boot from flash by moving the two jumpers together to B0_0 and B1_0.
You will have to reset the board once the image is uploaded to it.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/57023d13/docs/chapter1/try_markdown.md
----------------------------------------------------------------------
diff --git a/docs/chapter1/try_markdown.md b/docs/chapter1/try_markdown.md
index 4d6d7b3..526bf0c 100644
--- a/docs/chapter1/try_markdown.md
+++ b/docs/chapter1/try_markdown.md
@@ -18,4 +18,15 @@
* Click on "Help" in Mou and then on "Markdown Syntax Reference".
-* <font color="red"> Substitute a sentence of your own here </font>
\ No newline at end of file
+* <font color="red"> Substitute a sentence of your own here </font>
+
+
+
+---
+
+> <font color="red"> Note! </font>
+>> You will not be able to see the change immediately by refreshing your browser right after editign the Markdown file. You can only push the change to the Apache repository. So continue with the steps in [how_to_edit_docs.md](how_to_edit_docs.md).
+>>
+>> You can see the change on the website if/when a doc builder on the project team merges your changes to the master branch and generates the pages for the website.
+>>
+>> You do have the option to download MkDocs and preview the change by hosting the pages locally using its built-in web server. The steps are described in [how_to_edit_docs.md](how_to_edit_docs.md).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/57023d13/docs/index.md
----------------------------------------------------------------------
diff --git a/docs/index.md b/docs/index.md
index 592f9f0..9b37184 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -64,17 +64,17 @@ The chapter organization is outlined below. Each chapter will include one or mor
### Contributing to Documentation
-All content on this site is statically generated using [MkDocs](http://www.mkdocs.org) from documents written in Markdown and stored in the `docs` directory on the master branch in the [Documentation repository](https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git). As a documentation contributor you will modify in the desired markdown file or create new ones in the appropriate chapter subdirectory under `docs`.
+All content on this site is statically generated using [MkDocs](http://www.mkdocs.org) from documents written in Markdown and stored in the `docs` directory on the master branch in the [Documentation repository](https://git-wip-us.apache.org/repos/asf/incubator-mynewt-site.git). As a documentation contributor you will modify the desired markdown file or create new ones in the appropriate chapter subdirectory under `docs`.
To edit content in a Markdown file and be able to see how the changes look you may use desktop apps such as:
* [Mou](http://25.io/mou/) for Mac
* [Something like Mou](http://alternativeto.net/software/mou/?platform=windows) for Windows
-Click on [How to edit docs](chapter1/how_to_edit_docs.md) under "Get Started" to learn how to edit a sample file [try_markdown.md](chapter1/try_markdown.md) on Mynewt's documentation git repository.
+Click on the tutorial [How to edit docs](chapter1/how_to_edit_docs.md) under "Get Started" to learn how to edit a sample file [try_markdown.md](chapter1/try_markdown.md) on Mynewt's documentation git repository.
The static html content is generated and maintained in the asf-site branch in the documentation repository. Currently, the static html files are generated manually once a day. This will be automated in the future.
-You can preview the changes you have made on your desktop by installing MkDocs and starting up its built-in webserver as described in [MkDocs](http://www.mkdocs.org).
+If you wish, you may preview the changes you have made on your desktop by installing MkDocs and starting up its built-in webserver as described in [MkDocs](http://www.mkdocs.org). This step is optional but described in the tutorial.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/57023d13/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 8c2d1b8..a05b1a0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -3,19 +3,19 @@ site_url: http://mynewt.incubator.apache.org/index.html
pages:
- Home: 'index.md'
-- Get Started:
+- Chapter1 - Get Started:
- 'Newt Concepts': 'chapter1/newt_concepts.md'
- 'Blinky, The First Project': 'chapter1/project1.md'
- 'How to edit docs': 'chapter1/how_to_edit_docs.md'
- 'Sample doc to edit': 'chapter1/try_markdown.md'
-- Get Acclimated:
+- Chapter2 - Get Acclimated:
- 'Understanding Newt Terms': 'chapter2/vocabulary.md'
- 'Project 2': 'chapter2/project2.md'
- 'Project 3': 'chapter2/project3.md'
-- Newt Tool:
+- Chapter3 - Newt Tool:
- 'Command structure': 'chapter3/newt_ops.md'
- 'Command list': 'chapter3/newt_tool_reference.md'
-- Newt OS:
+- Chapter4 - Newt OS:
- 'Overview': 'chapter4/mynewt_os.md'
- 'Scheduler/Context Switching': 'chapter4/context_switch.md'
- 'Time': 'chapter4/time.md'
@@ -28,13 +28,13 @@ pages:
- 'Mbufs': 'chapter4/mbufs.md'
- 'Sanity': 'chapter4/sanity.md'
- 'Porting to other Platforms': 'chapter4/port_os.md'
-- Modules:
+- Chapter5 - Modules:
- 'Console': 'chapter5/console.md'
- 'Shell': 'chapter5/shell.md'
- 'Bootloader': 'chapter5/bootloader.md'
- 'File System': 'chapter5/filesystem.md'
- 'Test Utilities': 'chapter5/testutil.md'
-- Packaging it:
+- Chapter6 - Packaging it:
- 'Creating Packages': 'chapter6/dist.md'
markdown_extensions: