Cleaning up headers a bit

Author: Irit Arkin

docs/creating_apps/adding_exporters.md

@@ -1,10 +1,10 @@
-# Adding exporters 
+## Adding exporters
 
 This is a guide for adding exporters to the mbed OS tools. First, this document describes what an exporter is and what rules it follows. Then, it covers the structure of the export subsystem and the individual exporter. Finally, this document gives some implementation suggestions.
 
 <span class="notes">**Note:** All paths are relative to [https://github.com/ARMmbed/mbed-os/](https://github.com/ARMmbed/mbed-os/).</span>
 
-## What an exporter is
+### What an exporter is
 
 An exporter is a Python plugin to the mbed OS tools that converts a project using mbed CLI into one specialized for a particular IDE. For the best user experience, an exporter:
 
@@ -13,7 +13,7 @@ An exporter is a Python plugin to the mbed OS tools that converts a project usin
  - Has a single template file for each file type they produce. For example, an eclipse CDT project would have one template for `.project` files and one for `.cproject` files.
  - Does not call mbed CLI. It is possible to export from the website, which will not include mbed CLI in the resulting zip.
 
-## Export subsystem structure
+### Export subsystem structure
 
 The export subsystem is organized as a group of common code and a group of IDE or toolchain specific plugins.
 
@@ -25,11 +25,11 @@ The **common code** is contained in three files:
 
 An **IDE or toolchain specific plugin** is a Python class that inherits from the `Exporter` class and is listed in the `tools/export/__init__.py` exporter map.
 
-### Common code
+#### Common code
 
 The common code does two things: setting things up for the plugins, and providing a library of useful tools for plugins to use.
 
-#### Setup
+##### Setup
 
 The setup code scans for the resources used in the export process and collects the configuration required to build the project at hand.
 
@@ -41,15 +41,15 @@ These steps construct an object of one of the exporter plugin classes listed in
  * `flags` the flags that the mbedToolchain instance will use to compile the `c/cpp/asm` files if invoked.
  * `resources` a `Resources` object that contains many lists of files that an exporter will find useful, such as C and Cpp sources and header search paths. The plugin should use only the attributes of the Resources object because the methods are only used during setup time. You can view all available Resources class attributes in `tools/toolchains/__init__.py`.
 
-#### Plugin tools
+##### Plugin tools
 
 The other half of the common code is a library for use by a plugin. This API includes:
 
  * `gen_file` use Jinja2 to generate a file from a template.
  * `get_source_paths` returns a list of directories that contain assembly, C, C++ files and so on.
- * `group_project_files` group all files passed in by their containing directory. The groups are suitable for an IDE. 
+ * `group_project_files` group all files passed in by their containing directory. The groups are suitable for an IDE.
 
-### Plugin code
+#### Plugin code
 
 Plugin code is contained within a subdirectory of the `tools/export` directory named after the IDE or toolchain that the plugin is exporting for.
 For example, the uVision exporter's templates and Python code is contained within the directory `tools/export/uvision` and the Makefile exporter's code and templates within `tools/export/makefile`.
@@ -60,39 +60,39 @@ The Python code for the plugin should be:
 1. Imported into `tools/export/__init__.py`.
 1. Added to the exporter map.
 
-#### The `generate` method
+##### The `generate` method
 
-Each exporter is expected to implement one method, `generate`, which is responsible for creating all of the required project files for the IDE or toolchain that the plugin targets. 
+Each exporter is expected to implement one method, `generate`, which is responsible for creating all of the required project files for the IDE or toolchain that the plugin targets.
 
 This method may use any of the attributes and APIs included by the common code.
 
-#### The `TARGETS` class variable
+##### The `TARGETS` class variable
 
 Each exporter reports its specific target support through a class varibale, `TARGETS`. This class variable is simply a list of targets to which you can export. Requesting an export to a target that's not on the list will generate an error.
 
-#### The `TOOLCHAIN` class variable
+##### The `TOOLCHAIN` class variable
 
 Each exporter reports its specific toolchain it will use to compile the source code through a class variable `TOOLCHAIN`.
 
-#### The `NAME` class variable
+##### The `NAME` class variable
 
 Each exporter reports the name of the exporter through the class variable `NAME`. This matches the key in the `tools/export/__init__.py` exporter map.
 
-#### The `build` method
+##### The `build` method
 
-A plugin that would like to be tested by CI may implement the `build` method. 
+A plugin that would like to be tested by CI may implement the `build` method.
 
 This method runs after `generate` on an object that inherits from `Exporter`. It is responsible for invoking the build tools that the IDE or toolchain needs when a user instructs it to compile. It must return `0` on success or `-1` on failure.
 
-## Implementing an example plugin
+### Implementing an example plugin
 
 In this section, we walk through implementing a simple exporter, `my_makefile`, which is a simplified Makefile using one template.
 
 We will create two files and discuss their contents: `__init__.py` with the Python plugin code, and `Makefile.tmpl` with the template.
 
 As this plugin is named `my_makefile`, all of the support code will be placed into `tools/export/my_makefile`.
 
-### Python code for `__init__.py`
+#### Python code for `__init__.py`
 
 First, we will make our class a subclass of Exporter:
 ```python
@@ -126,7 +126,7 @@ TARGETS = [target for target, obj in TARGET_MAP.iteritems()
            if "GCC_ARM" in obj.supported_toolchains]
 ```
 
-#### Implementing the `generate` method
+##### Implementing the `generate` method
 
 To generate our Makefile, we need a list of object files the executable will use. We can construct the list from the sources if we replace the extensions with `.o`.
 
@@ -166,9 +166,9 @@ To render our template, we pass the template file name, the context and the dest
 self.gen_file('my_makefile/Makefile.tmpl', ctx, 'Makefile')
 ```
 
-### Template
+#### Template
 
-Now that we have a context object, and we have passed off control to the Jinja2 template rendering engine, we can look at the template Makefile, `tools/export/my_makefile/Makefile.tmpl`. 
+Now that we have a context object, and we have passed off control to the Jinja2 template rendering engine, we can look at the template Makefile, `tools/export/my_makefile/Makefile.tmpl`.
 
 Find documentation on what is available within a Jinja2 template [here](http://jinja.pocoo.org/docs/dev/templates/).
 
@@ -239,18 +239,18 @@ $(PROJECT).elf: $(OBJECTS) $(SYS_OBJECTS) $(LINKER_SCRIPT)
 	@$(LD) -T $(filter %{{link_script_ext}}, $^) $(LIBRARY_PATHS) --output $@ $(filter %.o, $^) $(LIBRARIES)
 ```
 
-## Suggested implementation
+### Suggested implementation
 
 There are several paths forward that can lead to an easily maintained exporter:
  - Specialize or alias the GNU ARM Eclipse exporter.
  - Specialize or alias the Eclipse + Make exporter.
  - Specialize the Make exporter.
- 
-### GNU ARM Eclipse
+
+#### GNU ARM Eclipse
 
 If your IDE uses Eclipse and uses the GNU ARM Eclipse plugin, then specialize or alias your exporter with the generic GNU ARM Eclipse.
 
-#### Alias
+##### Alias
 
 If you do not need any specialization of the export, then replace your exporters class in the `EXPORT_MAP` with the `GNUARMEclipse` class. For example, if KDS met all of these requirements, we could:
 
@@ -265,13 +265,13 @@ EXPORTERS = {
      'sw4stm32'    : sw4stm32.Sw4STM32,
 ```
 
-#### Specialization
+##### Specialization
 
 If you need more specialization and are using an Eclipse based IDE and the GNU ARM Eclipse plugin, then your exporter class inherits from the `GNUARMEclipse` class. For example (with KDS again):
 
 ```python
 from tools.export.gnuarmeclipse import GNUARMEcilpse
- 
+
 class KDS(GNUARMEcilpse):
      NAME = 'Kinetis Design Studio'
      TOOLCHAIN = 'GCC_ARM'
@@ -281,22 +281,22 @@ class KDS(GNUARMEcilpse):
          """Generate eclipes project files, and some KDS specific files"""
          super(KDS, self).generate()
          ...
- 
+
 ```
 
 After inheriting from the `GNUARMEclipse` class, specialize the generate method
 in any way you need.
 
-### Eclipse + Make
+#### Eclipse + Make
 
 If your IDE uses Eclipse and does not use the GNU ARM Eclipse plugin, you
-can use the "Unmanaged makefile" Eclipse exporter classes, `EclipseGcc`, 
-`EclipseArmc5` and `EclipseIar`. Much like the GNU ARM Eclipse section, you may 
+can use the "Unmanaged makefile" Eclipse exporter classes, `EclipseGcc`,
+`EclipseArmc5` and `EclipseIar`. Much like the GNU ARM Eclipse section, you may
 decide to alias or specialize.
 
-### Make
+#### Make
 
-If your IDE is not Eclipse based but can still use a Makefile, then you can specialize the Makefile exporter. Specializing the Makefile is actually how ARM mbed implemented the Eclipse + Make exporter. 
+If your IDE is not Eclipse based but can still use a Makefile, then you can specialize the Makefile exporter. Specializing the Makefile is actually how ARM mbed implemented the Eclipse + Make exporter.
 
 Creating an exporter based on the Makefile exporter is a two step process: inherit from the appropriate Makefile class, and call its generate method. Taking Eclipse + Make using GCC_ARM as an example, your exporter will look like:
 

docs/getting_started/troubleshooting_cli.md

@@ -1,10 +1,12 @@
- 
-## Troubleshooting with mbed CLI
 
-### Unable to import Mercurial (mbed.org) programs or libraries.
-1. Check whether you have Mercurial installed in your system path by  running `hg` in command prompt. If you're receiving "command not found" or a similar message, then you need to install Mercurial, and add it to your system path.
+### Troubleshooting with mbed CLI
 
-2. Try to clone a Mercurial repository directly. For example, `hg clone https://developer.mbed.org/teams/mbed/code/mbed_blinky/`. If you receive an error similar to `abort: error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.:590)`, then your system certificates are out of date. You need to update your system certificates and possibly add the host certificate fingerprint of `mbed.com` and `mbed.org`. Read more about Mercurial's certificate management [here](https://www.mercurial-scm.org/wiki/CACertificates).
+**Unable to import Mercurial (mbed.org) programs or libraries**
 
-### Various issues when running mbed CLI in Cygwin environment
-Currently mbed CLI is not compatible with Cygwin environment and cannot be executed inside it (https://github.com/ARMmbed/mbed-cli/issues/299).
+: 1. Check whether you have Mercurial installed in your system path by  running `hg` in command prompt. If you're receiving "command not found" or a similar message, then you need to install Mercurial, and add it to your system path.
+
+: 2. Try to clone a Mercurial repository directly. For example, `hg clone https://developer.mbed.org/teams/mbed/code/mbed_blinky/`. If you receive an error similar to `abort: error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.:590)`, then your system certificates are out of date. You need to update your system certificates and possibly add the host certificate fingerprint of `mbed.com` and `mbed.org`. Read more about Mercurial's certificate management [here](https://www.mercurial-scm.org/wiki/CACertificates).
+
+**Various issues when running mbed CLI in Cygwin environment**
+
+: Currently mbed CLI is not compatible with Cygwin environment and cannot be executed inside it (https://github.com/ARMmbed/mbed-cli/issues/299).

docs/getting_started/using_cli.md

@@ -29,7 +29,7 @@ The directories of Git and Mercurial executables (`git` and `hg`) need to be in
     * Compilers: GCC ARM, ARM Compiler 5, IAR.
     * IDE: Keil uVision, DS-5, IAR Workbench.
 
-#### Video tutorial for manual installation 
+#### Video tutorial for manual installation
 
 <span class="images">[![Video tutorial](http://img.youtube.com/vi/cM0dFoTuU14/0.jpg)](https://www.youtube.com/watch?v=cM0dFoTuU14)</span>
 
@@ -73,7 +73,7 @@ To install mbed-cli bash tab completion navigate to the `tools/bash_completion`
 
 [Full documentation here](tools/bash_completion/install.md)
 
-## Quickstart video
+### Quickstart video
 
 <span class="images">[![Video tutorial](http://img.youtube.com/vi/PI1Kq9RSN_Y/0.jpg)](https://www.youtube.com/watch?v=PI1Kq9RSN_Y)</span>
 
@@ -97,7 +97,7 @@ mbed CLI can create and import programs based on both mbed OS 2 and mbed OS 5.
 
 #### Creating a new program for mbed OS 5
 
-When you create a new program, mbed CLI automatically imports the latest [mbed OS release](https://github.com/ARMmbed/mbed-os/). Each release includes all the components: code, build tools and IDE exporters. 
+When you create a new program, mbed CLI automatically imports the latest [mbed OS release](https://github.com/ARMmbed/mbed-os/). Each release includes all the components: code, build tools and IDE exporters.
 
 With this in mind, let's create a new program (we'll call it `mbed-os-program`):
 
@@ -163,13 +163,13 @@ $ cd mbed-os-example-blinky
 ```
 
 You can use the "import" command without specifying a full URL; mbed CLI adds a prefix (https://github.com/ARMmbed) to the URL if one is not present. For example, this command:
- 
+
 ```
 $ mbed import mbed-os-example-blinky
 ```
 
 is equivalent to this command:
- 
+
 ```
 $ mbed import https://github.com/ARMmbed/mbed-os-example-blinky
 ```
@@ -191,7 +191,7 @@ $ mbed new .
 
 ### Adding and removing libraries
 
-While working on your code, you may need to add another library to your application or remove existing libraries. 
+While working on your code, you may need to add another library to your application or remove existing libraries.
 
 Adding a new library to your program is not the same as cloning the repository. Don't clone a library using `hg` or `git`; use `mbed add` to add the library. This ensures that all libraries and sublibraries are populated as well.