Improve detail of exporter addition docs #162

theotherjimmy · 2017-05-17T20:13:54Z

No description provided.

theotherjimmy · 2017-05-17T20:14:51Z

@AnotherButler, your assistance in all matters editing is appreciated.

theotherjimmy · 2017-05-17T20:17:16Z

@sg- @toyowata @screamerbg @maclobdell This is the documentation improvement I promised.

theotherjimmy · 2017-05-17T20:18:53Z

@AnotherButler @iriark01 I'm pretty sure that this document is not referenced from anywhere in other part of the contribution guide. Should we add a few more references to it?

screamerbg · 2017-05-17T21:47:32Z

This is great! Thanks, Jimmy

AnotherButler

@theotherjimmy This is fab. I left several suggested changes for you. Nice work.

AnotherButler · 2017-05-17T21:00:24Z

docs/cont/adding_exporters.md

@@ -1,18 +1,26 @@
 # Adding exporters 

-This is a guide for adding exporters to the mbed-os tools. It covers the structure of the export subsystem and the individual exporter.
+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.


Please lower case "this" in the second sentence.

AnotherButler · 2017-05-17T21:00:55Z

docs/cont/adding_exporters.md


 <span class="notes">**Note:** All paths are relative to [https://github.com/ARMmbed/mbed-os/](https://github.com/ARMmbed/mbed-os/).</span>

+## What is an exporter


Please add a question mark after "exporter" or rewrite as "What an exporter is"

AnotherButler · 2017-05-17T21:05:05Z

docs/cont/adding_exporters.md


 <span class="notes">**Note:** All paths are relative to [https://github.com/ARMmbed/mbed-os/](https://github.com/ARMmbed/mbed-os/).</span>

+## What is an exporter
+
+An exporter is a python plugin to the mbed OS tools that convert a project using mbed CLI into one specialized for a particular IDE. For the best user experience, an exporter should:


Please capitalize "Python".

AnotherButler · 2017-05-17T21:27:18Z

docs/cont/adding_exporters.md

+
+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:


Please change "we" to "you" for consistent person.

AnotherButler · 2017-05-17T21:36:59Z

docs/cont/adding_exporters.md

+ - Have 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.
+ - Not call mbed CLI. It is possible to export from the website, which will not include mbed CLI in the resulting zip.
+
+


Please delete the extra line.

AnotherButler · 2017-05-17T21:43:26Z

docs/cont/adding_exporters.md

+### GNU ARM Eclipse
+
+If your IDE uses Eclipse and uses the GNU ARM Eclipse plugin, then you should 
+specialize or alias your exporter with the generic GNU ARM Eclipse.


Note: Throughout the document, a lot of the text gets split onto separate lines. [Example: line break between "should" and "specialize"] Is this preventable?

AnotherButler · 2017-05-17T21:44:15Z

docs/cont/adding_exporters.md

+### 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 we 


Query: Who is "we" in this sentence? ARM mbed?

AnotherButler · 2017-05-17T21:45:18Z

docs/cont/adding_exporters.md

+
+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:


Query: When is "KDS" supposed to be capitalized, and when is it supposed to be lower case?

KDS, should be capitalized when referring to the IDE, and lower case when referring to the exporter.

AnotherButler · 2017-05-17T21:46:20Z

docs/cont/adding_exporters.md

+
+### GNU ARM Eclipse
+
+If your IDE uses Eclipse and uses the GNU ARM Eclipse plugin, then you should 


Please delete "you should" to match the format of the paragraphs after this one.

AnotherButler · 2017-05-17T21:48:05Z

docs/cont/adding_exporters.md


 <span class="notes">**Note:** All paths are relative to [https://github.com/ARMmbed/mbed-os/](https://github.com/ARMmbed/mbed-os/).</span>

+## What is an exporter
+
+An exporter is a python plugin to the mbed OS tools that convert a project using mbed CLI into one specialized for a particular IDE. For the best user experience, an exporter should:


Please delete "should", and change the mood of the bullets to reflect this. [Take > Takes, Use > Uses, Have > Has, Not call > Does not call]

toyowata · 2017-05-18T02:50:03Z

Hi @theotherjimmy
This is nice.

iriark01 · 2017-05-18T09:49:09Z

docs/cont/adding_exporters.md

@@ -1,18 +1,25 @@
 # Adding exporters 

-This is a guide for adding exporters to the mbed-os tools. It covers the structure of the export subsystem and the individual exporter.
+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.


mbed OS. That's one pound to the swear jar.

Ah, old text. I'll update it.

iriark01 · 2017-05-18T09:49:46Z

docs/cont/adding_exporters.md


 <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
+
+An exporter is a Python plugin to the mbed OS tools that convert a project using mbed CLI into one specialized for a particular IDE. For the best user experience, an exporter:


On docs.mbed, I don't think the list will be displayed unless there's a blank line between it and the paragraph above it (after "an exporter:")

Alright, I'll add that line.

theotherjimmy force-pushed the update-exporter-docs branch 2 times, most recently from ee8327a to 4374c79 Compare May 17, 2017 20:55

Improve detail of exporter addition docs

8f69af0

theotherjimmy force-pushed the update-exporter-docs branch from 4374c79 to 8f69af0 Compare May 17, 2017 20:56

AnotherButler reviewed May 17, 2017

View reviewed changes

Include edits suggested by Amanda

c43bd2a

theotherjimmy force-pushed the update-exporter-docs branch from 55381cb to c43bd2a Compare May 17, 2017 22:53

iriark01 reviewed May 18, 2017

View reviewed changes

Include Irit's edits

dae96b2

AnotherButler merged commit c3a83e2 into ARMmbed:5.4 May 19, 2017


		<span class="notes">Note: All paths are relative to [https://github.com/ARMmbed/mbed-os/](https://github.com/ARMmbed/mbed-os/).</span>

		## What is an exporter

		- Have 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.
		- Not call mbed CLI. It is possible to export from the website, which will not include mbed CLI in the resulting zip.


		### GNU ARM Eclipse

		If your IDE uses Eclipse and uses the GNU ARM Eclipse plugin, then you should

Improve detail of exporter addition docs #162

Improve detail of exporter addition docs #162

Uh oh!

Conversation

theotherjimmy commented May 17, 2017

Uh oh!

theotherjimmy commented May 17, 2017

Uh oh!

theotherjimmy commented May 17, 2017

Uh oh!

theotherjimmy commented May 17, 2017

Uh oh!

screamerbg commented May 17, 2017

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toyowata commented May 18, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!