DP: META - Create recommended standard/structure for repo doc files

[relativityboy]

As a repo creator, and as a Devportal maintainer I want documentation that both lives as close to the code as possible, and can be automatically consumed and displayed by the devportal in a controlled, organized, high-quality way.

AC

• [x] In # Results a recommeneded standard for documentation file format, general outline and directory/name structure.

[inertia186]

We might look at the .gemspec is organized, but use json instead.

[inertia186]

Result

One possibly critical component of this would be to ensure that the file contains a version number and/or tag/revision. This would require that version bumps manually update this file or that versions are automatically picked up from this file.

File named: steem-spec.json:

{
  "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"],
    "build_doc": "building",
    "contributing": "CONTRIBUTING.md",
    "license": "LICENSE.md"
  }
}

• name is the unixname of the tool/project, typically the github repo name.
• branches is where to look for stable vs. development branches. Basically, which branches people should look at depending on what they need to do.
• src and similar keys can be a string or array of strings if there are multiple.

[relativityboy]

This is, confusing in purpose to me.

• This doc (file) would
  • exist in every tutorial to be read by the scraper?
  • Live in devportal defining how a tutorial should be structured?
  • Live in the root of a repo and define... what exactly? (this is the least useful case to me, as the primary point of this story is to create a standard for the tutorials themselves, which a repo-instance general descriptor would do nothing for; and would not actually help establish a standard structure, but would instead contribute to diverging structures - which is bad as we neither need nor want that flexibility)
• If in every tutorial - if src is a list, what is the process for consuming? Also, what the type? ("lib" could be a file or dir) and if permitted, what's the behavior if a dir?

[inertia186]

Live in the root of a repo

Yes. I envision it as what I would want to know about the repo so I can generate, for example, a table of projects on a devportal page. Maybe it's a table that only lists projects written in certain languages. Or, I could use it to generate a header or footer with details on a page about a specific repo.

It doesn't have to live in the repo. It could live in the blockchain, if we had tooling and rules for editing (plus a list of accounts allowed to edit, apps that index the ops, so on). The nice thing about storing specs in the blockchain is that we could expand to community published steem-spec entries.

[relativityboy]

Hm. Your ideas have a lot of merit, we need to get into detail though. We need a described standard for how the tutorials are to be written so they're consumable. The original genesis of this story were some issues with the -rb repo's tutorial formatting, that came after an issue with the -js repo. I'd like us to have good reporting and validation on that.

So, we need to add descriptions standard for a directory that is something like our /tutorials directories.

As for the BC thing, interesting, but violates the I want documentation that both lives as close to the code as possible section of this story.

As it needs more work (rather than mild polish) moving back to In Progress.

[relativityboy]

Suggestions for Results regarding requirements for content that can be 'slurped' into the DP.

1. We add 2 attributes to the main repo descriptor mentioned in @inertia186's comment.

{
  "spec": {
    "content-src":"some root content dir",
    "content-category":"a string that would help the devportal place the content in the correct category"
  }
}

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

3. each child dir contains a README.md and a README.json

Most of the README.md format is TBD, but the first line should be # Some Title

README.json` contains

{
  "toc-title":"",
  "toc-description":"",
  "toc-order":2,
  "tags":[]
}

[inertia186]

We might need some mappings for relative paths if those happen, e.g., say if building.md links to example_config.ini. We could figure it out by guessing that the resource is in the same folder as the document, but adding resource mappings would take out the guess-work. Not only that, but it would allow us to freeze a mapping to a version.

building.json

{
  "toc-title":"Building steemd",
  "resource_mappings": [
    ["example_config.ini", "https://github.com/steemit/steem/blob/3b3ddef4ba5bd18324856ad8ed2909b3cb2716f5/doc/example_config.ini"]
  ]
}

[relativityboy]

@inertia186 - we currently assume that if links are relative, they're constructed to be valid within the current context, where-ever that is. While absolutes are left alone. You believe that's not enough?

[relativityboy]

Result 2

This spike went a little sideways in its focus. We'll followup in #379

We have a few major concepts for slurpable repos

1. A root json file describing what the repository is, some primary tags, and where to find documentation/tutorials.
2. Document/Tutorial specific 'file-format' (intra file structure) requirements (TBD)
3. A Per-Document/Tutorial .json file with enough data to populate a TOC type link, and possibly additional information.