Metadata-Version: 2.1
Name: cdocs
Version: 0.0.2
Summary: Cdocs is a super simple contextual help library
Home-page: https://github.com/dk107dk/cdocs
Author: David Kershaw
Author-email: dk107dk@hotmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# Cdocs
## A super simple contextual help library.

**Cdocs** is intended to help manage files for use in contextual help systems. The library knows how to find docs given a path. The expected use is to create an endpoint to retrieve docs from at runtime, or to pull docs into an app build.

Cdocs stores documentation as text files in a directory tree. Files are Jinja templates containing whatever doc format you prefer. Cdocs applies tokens to the templates, if found. Files can be concatenated or composed.

Cdocs can also be used to find text strings referred to as labels. Labels are stored as (non-template) JSON files in the same directory tree. The expected use is to find a JSON structure of labels for UI elements that would be seen in the same screen contextual help is available for.

Docs are stored in two directory trees: public and internal. The public tree is for your docs writers to store their content. Internal is for defaults and is expected to not be widely accessible. Requests for labels and tokens are aggregated from every directory below root, starting from the requested path.  The values found lowest in the directory tree win. Public values win over internal values.

Use a *config.ini* to set the documentation root directory, file extension, etc.  The contents should be similar to this:

> [docs]
>
> public = /Users/davidkershaw/dev/cdocs/docs/example
>
> internal = /Users/davidkershaw/dev/cdocs/docs/internal
>
> [defaults]
>
> notfound = [internal]/404
>
> [formats]
>
> ext = xml
>
> [filenames]
>
> tokens = tokens.json
>
> labels = labels.json


Cdocs has several ways of getting content:
- **get_doc**: docs at paths like */x/y/z* with the physical file being at *[root]/x/y/z.[ext]*. This is the "default" doc for the path. The result text will be treated as a jinja template. The template will receive a dict created from all the *[tokens].json* files from the doc's directory up to the root, and the same from the same directory under the internal tree.
- **get_labels**: labels as json for paths like */x/y/z* found as *[root]/x/y/z/labels.json*
- **get_doc**: docs at paths like */x/y/z#name* found as *[root]/x/y/z/name.[ext]*. These docs are processed in the same way as the default doc.
- **get_concat_doc**: docs as concats of files for paths like */x/y/z* found as *[root]/x/y/z/page.txt* where page.txt is a list of simple doc names to be concatenated. Simple doc names are the same as docs named by the *#name* path suffix. The files to be concatenated must be in the directory pointed to by the path.
- **get_compose_doc**: docs as jinja files at paths like */x/y/z/page.html* that compose pages where docs are pulled in using jinja expressions like:
*{{ get_doc('/app/home/teams/todos/assignee#edit_assignee') }}*
*get_compose_doc* requires the compose template be *.xml*, *.html* or *.md*. A compose doc could be referenced by a concat file, or vice versa, but the reference will only include the file contents; it will not be transformed.

### TODO:
- indicate a transformer for default and #name docs. E.g. to transform xml > md, md > html, etc.
- think about if all docs should be able to pull in other docs, not just the compose docs.
- think about if concat and compose docs should be transformed before being included in the other type. e.g. if /x/y/z/concat.txt included /x/compose.html then compose.html would be rendered before being concatenated.
- create a Flask Api for requesting docs and labels







