https://github.com/nativescript/docs-howto-extractor
A tool, extracting how-to articles from the NativeScript repo tests application
https://github.com/nativescript/docs-howto-extractor
Last synced: 8 months ago
JSON representation
A tool, extracting how-to articles from the NativeScript repo tests application
- Host: GitHub
- URL: https://github.com/nativescript/docs-howto-extractor
- Owner: NativeScript
- Archived: true
- Created: 2016-03-25T12:47:32.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2016-04-28T13:16:50.000Z (about 10 years ago)
- Last Synced: 2024-05-23T10:00:45.540Z (about 2 years ago)
- Language: TypeScript
- Size: 15.6 KB
- Stars: 0
- Watchers: 7
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# SnippetsExtractor
This tool would extract snippets from source fiels.
## How to Mark a Snippet
You need to follow these rules:
- Create a fully-functional unit-test that would contain your snippet.
- Start snippet with `// `
(module is the relative path of the module. Based on this path, a HowTo.md file
will be generated. Title is the string, used to display the link in the generated
documentation Table of Contents as well as the Description of the generated HTML file,
read by the Search Engines.
- Write md tags and comments by placing comment in the code file with // at the beginning.
- You must wrap the code within md tags that would indicate it is actually a code.
+ Start with: // ``` JavaScript
+ To output a comment here start with ////, two of them would be automatically removed.
+ Hide asserts within `// ` and `// `.
+ End with: // ```
- End with `// `
### Example:
``` JavaScript
exports.testFolderRename = function (){
//
// ## Setting a variable
// This example shows how to initialize myVar to 15.
// ``` JavaScript
//// Setting myVar to 15.
var myVar = 15;
//
console.assert(myVar == 15);
//
// ```
// That's how you set a myVar to 15.
//
}
```
**START OF SET-VAR.MD**
## Setting a variable
This example shows how to initialize myVar to 15.
``` JavaScript
// Setting myVar to 15.
var myVar = 15;
```
That's how you set a myVar to 15.
**END OF SET-VAR.MD**
## How Does it Work
The tool is node.js console application.
When run it will clean up its destination folder from md files.
Then scan the source filder for js files.
Each js file will be searched for some special comments described below.
When comments that mark a snippet are found the tool
would output an md in the destination folder.
Check the help.md for command line options.
### Snippet tags
Snippet are enclosed within the tags:
``` JavaScript
//
// This appends to /HOW-TO.md
var myVar;
//
```
The lines between these two tags are appended to a file
with the name in the opening tag.
### Hide tags
To hide code, that should not show in the snippet, wrap it with:
``` JavaScript
//
// This comment and the assert below are ignored.
console.assert(myvar == "myvalue");
//
```
### Comment Slashes
When comments within snippets are found, two of the leading slashes will be removed.
``` JavaScript
// ## This is H2 header
//// Setting myVar
var myVar = 15
```
Would output the md:
``` JavaScript
## This is H2 header
// Setting myVar
var myVar = 15
```
### Leading whitespace
Uniform leading whitespace would be removed so the snippet text is left aligned.
So there is no problem to use identation in your code. However it must be
eiter tabs or spaces. Do not mix tabs and spaces within the same snippet.
### Can not Handle Comments with /* and */