Skip to content

Commit f110b11

Browse files
robhrt7robhrt7
committed
Migrating docs to .md
1 parent ab10b87 commit f110b11

File tree

11 files changed

+210
-251
lines changed

11 files changed

+210
-251
lines changed

‎docs/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Engine documentation comes packed to every SourceJS instance, run `docs` section locally or visit http://sourcejs.com/docs.
1+
Engine documentation comes packed to every SourceJS instance, run `/docs` section locally or visit http://sourcejs.com/docs.

‎docs/api/readme.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Internal API documentation.

‎docs/auth/index.src

-65
This file was deleted.

‎docs/auth/readme.md

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Using GitHub Auth
2+
3+
## Quick Start
4+
5+
Before you start, please make sure that you have referenced GitHub App registered. Please visit [this link](https://developer.github.com/guides/basics-of-authentication/#registering-your-app) to get more information.
6+
7+
If you allready have registered app replace existed github api key and secret into your local options file, as mentioned [here](/docs/base/#5!).
8+
9+
Values, given below, are created as a demo. They are usable for [local instance](http://127.0.0.1:8080) at `127.0.0.1:8080`
10+
11+
```js
12+
github: {
13+
appId: "cf00a9e7ee5d9d6af36f",
14+
appSecret: "aebe08e0aa66f6911e4f54df81ce64c9d6e0003b"
15+
}
16+
```
17+
18+
Please take into account, that auth feature is turned off by default and you have to set related option: `options.modulesEnabled.auth` to `true` in your config.
19+
20+
After that, auth feature is able to use.
21+
22+
### Client-side auth control
23+
24+
Github auth module includes client-side controll. It should be included into your `header.inc.html` (if you have the overridden one). Here is the example:
25+
26+
```html
27+
<!-- header.inc.html content-->
28+
<a class="js-hook source_login"></a>
29+
<!-- header.inc.html content-->
30+
```
31+
32+
Auth uses `js-hook` and `source_login` classes for targeting. This hook is defined into `/assets/js/enter-the-source.js` file.
33+
34+
## Auth configuration
35+
36+
Auth configuration is availible from your instance options, as it was mentioned above. Here is the full options list:
37+
38+
```js
39+
// localStorage key for client-side user object
40+
'storageKey': 'sourcejsUser',
41+
// avatar stub URL
42+
'defaultAvatarURL': '/source/assets/i/unknown.gif',
43+
// set of client-side control classes
44+
'classes': {
45+
'controlsWrapper': 'source_login',
46+
'loginButton': 'source_login-button',
47+
'avatar': 'source_login-avatar',
48+
'anonymous': 'anonymous',
49+
'hook': 'js-hook'
50+
},
51+
// login/logout button labels
52+
'labels': {
53+
'login': 'Login',
54+
'logout': 'Logout'
55+
}
56+
```
57+
58+
## Auth modules usage
59+
60+
Both server-side and client-side auth parts are able to use from other modules.
61+
62+
Server-side part provides [The everyauth](https://github.com/bnoguchi/everyauth) API whitch it is based on. Also there are methods either to get or to set GitHub user into temporary users storage.
63+
64+
Client-side part allows to login/logout using Github, to check if user is logined and to get user data.

‎docs/clarify/index.src renamed to ‎docs/clarify/readme.md

+5-19
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,21 @@
1-
<h1>Clarify - Spec Section Testing Environment</h1>
1+
# Clarify - Spec Section Testing Environment
22

3-
<p class="source_info">
4-
SourceJS middleware, that allows to open separate documentation examples in custom or clean environment for component testing and development.
5-
</p>
3+
SourceJS middleware, that allows to open separate documentation examples in custom or clean environment for component testing and development.
64

7-
<section class="source_section">
8-
<markdown>
95
## General information
106

117
Clarify is an [expressJS](http://expressjs.com/) middleware built into SourceJS engine. Easy configurable through URL parameters in Spec pages:
128

13-
```source_wide-code
9+
```html
1410
http://localhost:8080/docs/spec/?clarify=true&sections=1.1
1511
```
1612

1713
When enabled, Clarify uses [JSdom](https://github.com/tmpvar/jsdom) for getting specified sections and wrap them in pre-defined or user templates. If you're using SourceJS HTML API, Clarify can be configured to take data directly from API storage as well.
1814

1915
Clarify page is enhanced with helper panel, where you can chose any option available:
2016

21-
<a href="/docs/spec/?clarify=true&sections=1.1"><img src="i/clarify.png" alt="image" style="margin-left: -57px;"></a>
22-
</markdown>
23-
</section>
17+
[<img src="i/clarify.png" alt="image" style="margin-left: -57px;">](/docs/spec/?clarify=true&sections=1.1)
2418

25-
<section class="source_section">
26-
<markdown>
2719
## List of parameters
2820

2921
| Param | Value | Default setting | Description |
@@ -36,11 +28,7 @@ Clarify page is enhanced with helper panel, where you can chose any option avail
3628
| tpl | template-name | default | Define EJS template name to render sections. Templates are defined in `core/views/clarify/` and `user/core/views/clarify/`, user templates overrides core. |
3729

3830
To play around with available URL params, open [Clarify page](/docs/spec/?clarify=true&sections=1.1) and fill the helpers form below.
39-
</markdown>
40-
</section>
4131

42-
<section class="source_section">
43-
<markdown>
4432
## Use cases
4533

4634
Clarify is covering wide range of use cases:
@@ -50,6 +38,4 @@ Clarify is covering wide range of use cases:
5038
* Focusing on single example during development
5139
* Isoleted page for automated testing
5240
* Responsive design testing
53-
* Fast transfer of code examples to templates
54-
</markdown>
55-
</section>
41+
* Fast transfer of code examples to templates

‎docs/data-nav/index.src

-104
This file was deleted.

‎docs/data-nav/readme.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Autogenerated Navigation
2+
3+
Navigation generation in Source in fully automated, and allows us to call any list of specs using simple HTML hooks.
4+
5+
## Embedding
6+
7+
Common scheme of embedding looks like this:
8+
9+
```html
10+
&lt;div class="source_catalog" data-nav="/docs">&lt;/div>
11+
```
12+
13+
Required attribute `data-nav` names the catalogue to be displayed. Inserting mentioned code in any Source page a navigation like this will be generated:
14+
15+
<div class="source_catalog" data-nav="/docs"></div>
16+
17+
18+
### Absolute pathя
19+
20+
We recommend using absolute paths, as they are more stable and predictable.
21+
22+
Output of:
23+
24+
```html
25+
&lt;div class="source_catalog" data-nav="/docs/api">&lt;/div>
26+
```
27+
28+
Renders like this:
29+
30+
<div class="source_catalog" data-nav="/docs/api"></div>
31+
32+
Also, you could leave a direct path to any Spec:
33+
34+
```html
35+
&lt;div class="source_catalog" data-nav="/docs/clarify">&lt;/div>
36+
```
37+
38+
<div class="source_catalog" data-nav="/docs/clarify"></div>
39+
40+
41+
### Relative path
42+
43+
Relative paths are also supported, but are less stable (with some issues):
44+
45+
```html
46+
&lt;div class="source_catalog" data-nav="api">&lt;/div>
47+
```
48+
49+
<div class="source_catalog" data-nav="api"></div>
50+
51+
52+
## Headings and description automatic output
53+
54+
By default, contents of `info.json` is used to display title and additional information:
55+
56+
```html
57+
&lt;div class="source_catalog" data-nav="/docs">&lt;/div>
58+
```
59+
60+
<div class="source_catalog" data-nav="/docs"></div>
61+
62+
If there is no description, or you want to leave custom text, just use this extra markup:
63+
64+
```html
65+
&lt;div class="source_catalog" data-nav="/docs">
66+
&lt;h2 class="source_catalog_title">Custom Title&lt;/h2>
67+
&lt;div class="source_catalog_tx">Custom description for catalogue.&lt;/div>
68+
&lt;/div>
69+
```
70+
71+
<div class="source_catalog" data-nav="/docs">
72+
<h2 class="source_catalog_title">Custom Title</h2>
73+
<div class="source_catalog_tx">Custom description for catalogue.</div>
74+
</div>
75+
76+
77+
## Filtering by tag
78+
79+
As we can define different tags for specs in `info.json` files (more in [docs](/docs/info-json/)), we can use them to filter custom navigation tree.
80+
81+
82+
```html
83+
&lt;div class="source_catalog" data-nav="/docs" data-tag="templates">&lt;/div>
84+
```
85+
86+
<div class="source_catalog" data-nav="/docs" data-tag="templates">
87+
<h2 class="source_catalog_title">Specs with `templates` tag</h2>
88+
</div>
89+
90+
To call all specs without a tags, you can filter by `"without-tag"` string.

0 commit comments

Comments
 (0)