...
Name | Role | Task | |
---|---|---|---|
Bobbi Muscara | bobbi@ledgeracademy.com | Task Force Director | Organize Group |
John Carpenter | john@globalblockchainsummit.com | Task Force Member | Organize and Help Create Documentation Standards |
Sara Moix | saraisabelmoix@gmail.com | Task Force Member | Help Organize and Support |
Benjamin Weymouth | benjamin.weymouth@gmail.com | Task Force Member | Help Organize and Support |
Determine The Current Status of all Projects/Tools/Libraries
- The purpose of this section is to review the existing documentation hosting setup for multiple Hyperledger Projects.
- Key Takeaways:
- Most Projects use ReadtheDocs
- Most of those ReadtheDocs projects use either Sphinx, Restructured Text for markdown or a theme enhancer like MKdocs
- A few projects use a non-traditional documentation hosting service, or do not use any documentation hosting service.
- Might be prudent to standardize / harmonize the documentation since most projects utilize ReadtheDocs
- Matrix Sphinx is a tool that allows us to create documentation using simple markup languages and generate multiple output formats: HTML, LaTeX, PDF, Confluence, ePub, and plain text.
- https://developers.google.com/season-of-docs
https://readthedocs.org/
Project | Documentation | File Type / Documentation Service | Notes | Location | Wiki Page Categories | Repos | ||||
---|---|---|---|---|---|---|---|---|---|---|
Fabric | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs. | https://hyperledger-fabric.readthedocs.io/en/latest/ | Documentation & Resources
| Repository | ||||
Besu | READTHEDOCS | .MKDOC ( Material design) and .MD files | Hyperledger Besu and its documentation are licensed under Apache 2.0 license / This Readthedocs.org documentation is maintained with love by Hyperledger Besu community. Made with Material for MkDocs | https://besu.hyperledger.org/en/stable/ | DocumentationDocumentation on Hyperledger Besu can be found here: https://besu.hyperledger.org/ | Repositories | ||||
Sawtooth | READTHEDOCS | .RST FILE and .MD FILES | Sawtooth 1.2 documentation has not yet been completely converted to the new site’s format. You can find the documentation in sphinx-doc rst format at: | https://sawtooth.hyperledger.org/docs/1.2/ | Documentation | Repositories | ||||
Iroha | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs. | https://iroha.readthedocs.io/en/develop/ | Documentation | Repositories | ||||
Indy | READTHEDOCS | .RST FILE and .MD FILES | Built with Sphinx using a theme provided by Read the Docs. | https://indy.readthedocs.io/en/latest/ | Documentation
| Repositories | ||||
Aries | READTHEDOCS | .RST FILE and .MD FILES | ReadtheDocs | Read me bring you to edx classes. | DocumentationFor those new to the Aries community, Trust over IP and verifiable credentials, Linux Foundation provides two courses about the concepts and technology:
The latter is obviously more focused on Aries, with the first chapter providing a summary of the former course, and a series of hands on labs based on Aries implementations. | RepositoriesNote that while the frameworks listed below are written in a specific, identified language, for the the business layer applications built on top of the frameworks can be implemented in any language. https://github.com/hyperledger/aries https://github.com/hyperledger/aries-rfcs https://github.com/hyperledger/aries-cloudagent-python https://github.com/hyperledger/aries-framework-dotnet https://github.com/hyperledger/aries-framework-go https://github.com/hyperledger/aries-framework-javascript https://github.com/hyperledger/aries-vcx https://github.com/hyperledger/aries-agent-test-harness https://github.com/hyperledger/aries-mobile-test-harness https://github.com/hyperledger/aries-mobile-agent-react-native https://github.com/hyperledger/aries-mobile-agent-xamarin All Aries repositories - https://github.com/hyperledger?utf8=%E2%9C%93&q=aries&type=&language= | ||||
Bevel | READTHEDOCS | .RST FILE and .MD FILES | © Copyright 2021, Hyperledger Bevel.Revision Built withSphinxusing athemeprovided byRead the Docs. | https://hyperledger-bevel.readthedocs.io/en/latest/introduction.html | Documentation | Repositories
| ||||
Cactus | READTHEDOCS | RST FILE and .MD FILES markdown or reStructuredText files with the standard theme | Cactus | Google Docs | Documentation is not on one platform for Cactus. ** Needs centralized ReadTheDocs with all project information. | Documentation | Repositories | |||
Caliper | READTHEDOCS /MKDocs | .RST FILE and .MD FILES Note: also uses markdown or reStructuredText files withyml for Mk Docs | powered by MkDocs and Material for MkDocs ="Jekyll v3.9.2" /> | https://hyperledger.github.io/caliper/ | Documentation: https://hyperledger.github.io/caliper/ | RepositoriesSource code: https://github.com/hyperledger/caliper Documentation: https://hyperledger.github.io/caliper/ | ||||
Cello | Google Docs | READTHEDOCS | .RST FILE and .MD FILESmarkdown or reStructuredText files with a different theme | https://github.com/hyperledger/cello/blob/main/README.md | DocumentationLatest Docs | RepositoriesSource Code: https://github.com/hyperledger/cello/ Documentation https://cello.readthedocs.io/en/latest/ | ||||
Firefly | JUSTThe Docs | https://just-the-docs.github.io/just-the-docs/ ** Just the Docs is different from ReadtheDocs. Might be easier to stick to one Layout. | This site uses Just the Docs, a documentation theme for Jekyll. | https://hyperledger.github.io/firefly/t | https://hyperledger.github.io/firefly/. | Repositories | ||||
Grid |
| ** Could be JusttheDocs, but it's unclear which documentation platform or theme they are using. We know Jekyll is used but that could be any number of Documentation hosting services. | <!-- Begin Jekyll SEO tag v2.8.0 → Jekyll v3.8.6 | The Hyperledger Grid documentation is available on the Grid website: Hyperledger Grid Documentation | Repositories | |||||
Transact | docs.rs | http://github.com/hyperledger/transact ** Uses a different service: Docs.rs, the documentation hosting service | DocumentationThe Hyperledger Transact API documentation is available on crates.io (click "Documentation"): https://crates.io/crates/transact | Repositories | ||||||
Ursa | docs.rs | https://github.com/hyperledger/ursa-docs **Unclear: the documentation is on the github and on Docs.rs | https://rust-lang.github.io/mdBook/ | Documentation | Repositories | |||||
...
- Cosmos has an updated / web3 look and feel to the UI.
- Landing page comparison: Cosmos provides a direct and immediate choice between conceptual and Quickstart / Developer Tutorials.
- Introduction comparison: similar themes addressed: history, backgrounder, orientation to product
- Key Concepts: both start with Key Concepts: blockchain, smart contracts, etc. Fabric is more comprehensive from a conceptual standpoint.
- Cosmos documentation assumes the audience knows blockchain basics, whereas Fabric is more newcomer friendly.
- Tutorials comparison: Fabric are built-in, while the Cosmos tutorials takes me to an entirely new page, new UI, new layout. (not user-friendly)
- Cosmos Tutorials means data is duplicated, developer has to start from scratch.
Review of ReadtheDocs Syntax, Sphinx, and reStructured SyntaxReadtheDocs Syntax, Sphinx, and reStructured Syntax
Since many Hyperledger projects use ReadtheDocs, it is important to have an understanding of the underlying structure of the platform. Thus, this This section highlights some of the syntax, capabilities and limitations of the ReadtheDocs structure. This is salient because the documentation of various Hyperledger projects relies on the ReadtheDocs platform. documentation hosting system. structure.
ReadtheDocs Highlights:
- Hyperledger documentation on ReadtheDocs is populated by files from the various Hyperledger project GitHub pages
- Those GitHub pages are synced with the ReadtheDocs platform and Pull Requests sync up to an index.rst file
- The index.rst file, as the extension might imply, is built upon Sphinx and reStructured syntax. (RST stands for reStructured)
- Sphinx and reStructured have their own syntax, formatting and are designed specifically for formatting documentation
- Matrix Sphinx is a tool that allows us to create documentation using simple markup languages and generate multiple output formats: HTML, LaTeX, PDF, Confluence, ePub, and plain text.
ReStructured Text:
- reStructured is not a full fledged markdown language, but does allow for some customization
- Myriad options for text formatting is available
- images and images with hyperlinks are available
- various themes are available
- backgrounds for code snippets like dark mode are available
- Tables, References / Bibliographic citations and a Table of Contents are available
...
1. Location of Documentation: we recommend ReadtheDocs
2. Markup Language
3. Template
...
Create Documentation Best Practice badging system.
Internal:
6/6
6/2
Task: Check out https://docs.cosmos.network/ for a comparison
...