DP: META - Create recommended standard/structure for slurpable repos

[relativityboy]

Continue the process outlined in #297 - formalize the structure discussed there, and extend it with specific tutorial structure recommendations that include notation within .md files and .js, .py,.rb files so that links between text and code blocks can be established, and parsed by devportal scripts into "inline" tutorials as we have now, and code-walks.

AC
The following in # Results and in SLURPABLE-REPOS.md located at the root of this repo

• choose file name for metadata, meta.json or README.json, etc
• specification for overall repo meta.json
• specification for individual tutorial meta.json
• specification for tutorial file-structure, and file-format so that src files & .md files can have appropriate bits linked
• Update our CONTRIBUTING.md to the current standard, with our sugar added.
• CONTRIBUTING.md also includes a section about getting a slurpable repo added to our rake tasks, and a link to SLURPABLE-REPOS.md.

[relativityboy]

Result

Configuration file names.

All configuration filenames should be slurpable.json

Basic folder structure

There is one root content source folder, content-dir, that contains a set of child folders. Each child folder corresponds to a complete article/content-item/tutorial.

Root .md

A root .md file may be specified in the root slurpable.json, for optional interpolation and inclusion by the slurper.

content-item folders

Each content-item folder will have one .md file text-src for consumption. It may also have multiple source code files for consumption code-src.

The .md file's contents may be interleaved with the source code files' contents, (Standard TBD pending the creation or selection of a library capable of doing this (supports more reliable/automatic tutorial updates, dynamic playground loading and code-walk creation). If there is not a text-src file to start from, the text-default file will be used, but will not go through the interleaving process. The values of all these properties are set in the root slurpable.json file.

The presence of a force-text-default:true attribute within a specific content-item folder's slurpable.json file will force the use of the default file for that content-item.

Root repo file

A root slurpable.json file describing what the repository is, some primary tags, and where to find documentation/tutorials.**

{
    "spec": {
        "name": "appname",
        "version": "1.0.0",
        "authors": ["<Firstname Lastname> email@address.com"],
        "summary": "Short summary, tool-tip sized.",
        "description": "Longer description, one paragraph or two at most.",
        "repo": "https://github.com/steemit/project",
        "branches": {
            "stable": "stable",
            "develop": "develop"
        },
        "language": "go",
        "src": ["lib"],
        "test": ["tests"],
        "doc": ["docs"],
        "content-dir": {
                "root":"some root content dir",
                "code-src":["a list of application files"],
                "text-src":"some .md file",
                "text-default":"README.md"
        }
        "content-category":"a string that would help the devportal place the content in the correct category",
        "build_doc": "building",
        "contributing": "CONTRIBUTING.md",
        "license": "LICENSE.md"
    }
}

the folder represented by content-src.root contains a set of child dirs. each representing a page.

3. each child dir contains a README.src.md or README.md and a slurpable.json

{
    "toc-title":"",
    "toc-description":"",
    "tags":[],
    "force-text-default":true,
    "resource_mappings": [
        ["example_config.ini", "https://github.com/steemit/steem/blob/3b3ddef4ba5bd18324856ad8ed2909b3cb2716f5/doc/example_config.ini"]
    ]
}

[inertia186]

Yep, that's a good start. In terms of what we really need right now, it's mostly just toc-title and toc-description. The rest of it is future-proofing.

[relativityboy]

Yup. We have the spec for when we need it. Without a goal and a map, it's roulette with Russians.