document doc content services

devdocs/INDEX.md

@@ -0,0 +1,6 @@
+# Developer Docs and RFCs
+
+This directory is where new ideas or developer guides will be organized for now. They may eventually find their way into
+a developer-focused documentation section.
+
+

devdocs/bundled_docs.md

@@ -0,0 +1,31 @@
+# Bundled Docs
+
+In order to keep the structure of NoSQLBench modular enough to allow for easy extension by contributors, yet cohesive in
+how it presents documentation and features to users, it is necessary to provide internal services which aggregate
+content by subject matter into a consumable whole that can be used by the documentation system.
+
+# MarkdownDocs Service
+
+The primary markdown service that is meant to be consumed by the documetnation system is known simply as
+
+    MarkdownDocs
+
+Static methods on this class will provide all of the markdown content in pre-baked and organized form. The markdown
+service is responsible for reading all the raw markdown sources and organizing their content into a single cohesive
+structure. MardownDocs finds all content that is provided by individual MarkdownProvider services, as described below.
+
+All of the rules for how raw markdown content is to be combined are owned by the MarkdownDocs service.
+
+# MarkdownProvider Service
+
+The `MarkdownProvider` service is responsible for bundling the raw markdown for a path within a NoSQLBench module. Each
+
+module that wishes to publish markdown docs to users must provide one or more MarkdownProvider services via SPI. This is
+most easily done with a `@Service(MarkdownProvider.class)` annotation.
+
+The MarkdownProvider service provides all of the individual markdown files it finds indirectly as
+io.nosqlbench.nb.api.content.Content, which allows the internal file content to be read appropriately regardless of
+whether it comes from a classpath resource stream, a file on disk, or even a dynamic source like function metadata.
+
+
+

devdocs/docsys.md

@@ -0,0 +1,26 @@
+# DocSys Design
+
+## Future
+
+### Front Matter Everything
+
+- Only markdown files which contain front matter will be considered user-facing docs.
+- Front matter will specify the namespace and/or names under which the included file should appear
+- Front matter will include search meta and related topics
+- Front matter will contain all the meta data that any client app needs to create a basic topic index or menu.
+- Front matter will specify whether or not to include the markdown in command line help.
+- Front matter will specify whether or not to include the markdown in web help.
+- Front matter will specify the topic path for the included.
+
+### Internal APIs
+
+- All markdown sources will be provided uniformly behind a markdown service type with SPI, like _MarkdownProvider_
+- Services and Static contexts will be supported equally.
+- MarkdownProvider data will have digest level info, which is exactly the frontmatter required above.
+
+### Searching
+
+- A standard search index payload in JSON form will be cachable by clients.
+- The initial phase of search will contain only meta and topic level matching.
+- A subsequent phase may include a compact or compressed form of FTS searching.
+