Review and test out git based documentation system for Sinar NGOs

[samqi]

docs

[samqi]

Had tested and stored review elsewhere, pasting here for review.

1. github project wiki Home Is already git based (see bottom right) No template features

2. readthedocs

   • sphinx & rst based is the default
   • python mkdocs exist and is more suitable to sinar
   • mkdocs is the Static Site Generator linked to ReadTheDocs. Useful read related to python mkdocs , it shows that mkdocs is one of the more mature open source projects related to docs and can use with and without readthedocs
   • pages, templates created via cli (readthedocs via mkdocs handles the linkage)
   • can edit MD in Github
   • template options exists
   • continous delivery platform
   • if you update github it will auto build into domain
   • github actions autocreated
   • used by some civic tech comapnies
   • also see the newer comment for more info

3. gitbook

   • gui based markdown generated is on gitbooks Web UI
   • team collaboration requires paid service
   • used by civic tech such as civic switchboard
   • also see the newer comment for more info

For above, can see this comparison of ReadTheDocs vs Gitbooks.io

4. other SSG with github.io pages
   • readthedocs vs using github pages (github.io)

There are several Python-based static site generators that work with Markdown. One of the most popular is Pelican. Here's a brief overview:

1. Pelican

• Primary Language: Python
• Input Format: Markdown, reStructuredText

• Description: Pelican is a robust, flexible static site generator that takes content written in Markdown or reStructuredText and converts it into static HTML files. It has a rich ecosystem of plugins and themes and supports Jinja2 templates for customization.

  Features:

  • Supports articles (with categories and tags) and pages.
  • Integrates with external services, like Disqus for comments and Google Analytics.
  • Offers a variety of plugins and themes.
  • Easily deploys to services like GitHub Pages, S3, etc.

If you are comfortable with Python and want something other than MkDocs, Pelican is an excellent choice due to its flexibility and active community.

2. Lektor

• Primary Language: Python
• Input Format: Markdown

• Description: Lektor is an extensible, file-based content management system. It's not just a static site generator but provides a web-based UI for content editing, making it somewhat unique.

  Features:

  • Built-in admin UI for editing.
  • Database-free, all data is stored in flat text files.
  • Plugin system for extensibility.

3. Nikola

• Primary Language: Python
• Input Format: Markdown, reStructuredText, IPython (Jupyter)

• Description: Nikola generates static websites and blogs, with feeds, comments, media galleries, and an archive. It’s designed for being fast and easy to use.

  Features:

  • Supports multiple input formats.
  • Extensible via plugins.
  • Provides a built-in web server and deployment tools.

[samqi]

Basic structure and workflow of ReadTheDocs (RTD) and MkDocs for generating Git-based site documentation.

1. ReadTheDocs (RTD)

   +---------------------------------------------+
   |               Your Git Repository            |
   |   +---------------------------------------+  |
   |   |     .rst (reStructuredText) Files     |  |
   |   +---------------------------------------+  |
   +---------------------------------------------+
                  |
                  | Push/Update
                  |
                  v
   +---------------------------------------------+
   |            ReadTheDocs Platform             |
   |   +-------------------+    +-------------+   |
   |   | Sphinx Generator  |-->|  HTML Site  |   |
   |   +-------------------+    +-------------+   |
   +---------------------------------------------+
                  |
                  | Hosted
                  |
                  v
   +---------------------------------------------+
   |             ReadTheDocs Web UI              |
   +---------------------------------------------+

   Explanation:

   • You write your documentation in reStructuredText (.rst) format and commit them to your Git repository.
   • When you push or update your documentation, RTD automatically detects these changes.
   • ReadTheDocs uses Sphinx to generate an HTML site from your .rst files.
   • The generated documentation is then made available via the ReadTheDocs web UI.

2. MkDocs

   +---------------------------------------------+
   |               Your Git Repository            |
   |   +---------------------------------------+  |
   |   |          .md (Markdown) Files         |  |
   |   +---------------------------------------+  |
   +---------------------------------------------+
                  |
                  | Push/Update
                  |
                  v
   +---------------------------------------------+
   |                 MkDocs Tool                 |
   |   +-------------------+    +-------------+   |
   |   | MkDocs Generator  |-->|  HTML Site  |   |
   |   +-------------------+    +-------------+   |
   +---------------------------------------------+
                  |
                  | Hosted (Optionally on RTD or other platforms)
                  |
                  v
   +---------------------------------------------+
   |             Web UI (e.g., GitHub Pages, RTD)   |
   +---------------------------------------------+

   Explanation:

   • You write your documentation in Markdown (.md) format and commit them to your Git repository.
   • Upon pushing or updating your documentation, you use the MkDocs tool to generate an HTML site.
   • The generated site can then be hosted on platforms like ReadTheDocs, GitHub Pages, or any other server.

Both RTD and MkDocs are tools to generate static site documentation from source files. While RTD traditionally uses Sphinx and reStructuredText, MkDocs uses its generator and Markdown. Both can be integrated with version control systems (like Git) to automate the generation and deployment of updated documentation.

[samqi]

GitBook allows for documentation generation and hosting, but it has its distinct flow and user interface. Here's a block diagram representation of how GitBook works for generating Git-based site documentation:

+---------------------------------------------+
|               Your Git Repository            |
|   +---------------------------------------+  |
|   |          .md (Markdown) Files         |  |
|   +---------------------------------------+  |
|   +---------------------------------------+  |
|   |       Additional Assets (Images, etc.)|  |
|   +---------------------------------------+  |
+---------------------------------------------+
                   |
                   | Sync (Webhooks/Integrations)
                   |
                   v
+---------------------------------------------+
|                GitBook Platform              |
|   +---------------------------------------+  |
|   |       GitBook Editor & Interface      |  |
|   +---------------------------------------+  |
|   +-------------------+    +-------------+   |
|   | GitBook Generator |-->|  HTML Site  |   |
|   +-------------------+    +-------------+   |
+---------------------------------------------+
                   |
                   | Hosted & Publicly Accessible
                   |
                   v
+---------------------------------------------+
|                GitBook Web UI                |
+---------------------------------------------+

Explanation:

• You write your documentation in Markdown (.md) format and commit them to your Git repository. Additionally, assets such as images, diagrams, etc., can be stored in the same repository.

• Through GitBook's integration features, changes made to your Git repository (usually via webhooks) can be synchronized with the GitBook platform.

• The GitBook platform provides a user-friendly editor and interface, allowing collaborators to make changes directly on the platform if needed.

• The platform uses its proprietary generator to turn the Markdown files and other assets into an interactive, well-formatted HTML site.

• The generated documentation is then hosted on the GitBook Web UI, making it publicly accessible.

With GitBook, the advantage is the seamless integration of a Git workflow with a rich, web-based editing experience. It merges the strengths of version control and a user-friendly documentation platform.

---

Many civic tech has reduced the usage of Gitbook since 2016/17 once they changed the business model and linitations to the free versions.

[samqi]

• Caveats: Github repo based wiki are only free for public repositories; private repository requires a subscription upgrade