Handle Our Internal Docs

[curtismchale]

Source @lukefretwell @curtismchale

We need to centralize and formalize our internal documentation process.

• docs options: https://github.com/testthedocs/awesome-docs

I've had Docusaurus, Sphinx, and 'Read the Docs' recommended as open source documentation tools.

The ultimate goal is to have everything out of our private Obsidian Repo and Google Docs into a web accessible (password protected) site.

[lukefretwell]

Read the Docs

https://github.com/readthedocs/readthedocs.org

Read the Docs is an open-source documentation hosting platform that automates the process of building, hosting, and deploying documentation for software projects. It is widely used by developers and project teams to publish and maintain their documentation in an organized and accessible manner. Here's an overview of Read the Docs:

1. Documentation Hosting: Read the Docs provides a centralized platform for hosting and managing documentation. It allows project teams to publish their documentation in a user-friendly format accessible to developers, users, and contributors.

2. Automated Builds: Read the Docs automates the process of building documentation from source code repositories. It supports popular version control systems like Git, Mercurial, and Subversion. Whenever a project's documentation repository is updated, Read the Docs automatically triggers a build process to generate the updated documentation.

3. Markup Language Support: Read the Docs supports multiple markup languages for writing documentation, including reStructuredText, Markdown, and Sphinx. This flexibility allows developers to choose the markup language that best suits their needs and preferences.

4. Versioning and Branching: Read the Docs supports versioning and branching, allowing users to view documentation specific to different versions or branches of a project. This feature is valuable for projects with multiple releases or development branches.

5. Search Functionality: Read the Docs includes a powerful search functionality that enables users to search for specific topics, keywords, or phrases within the documentation. This feature helps users quickly find the information they need.

6. Integration with Continuous Integration: Read the Docs can be integrated with Continuous Integration (CI) tools, such as Travis CI and CircleCI. This integration allows documentation builds to be triggered automatically upon code changes, ensuring that the documentation remains up to date with the latest codebase.

7. Customization and Theming: Read the Docs offers customization options to tailor the appearance and layout of the hosted documentation. Users can choose from various pre-built themes or create custom themes to match their project's branding and style.

8. Statistics and Analytics: Read the Docs provides statistics and analytics to track the usage and popularity of documentation. It offers insights into page views, search queries, and other metrics, helping project teams understand how their documentation is being utilized.

9. Collaboration and User Permissions: Read the Docs supports collaboration by allowing multiple contributors to work on the documentation. It provides user permission settings to control access and editing rights, ensuring that only authorized individuals can make changes to the documentation.

10. Community and Open Source: Read the Docs is an open-source project with an active community of developers contributing to its development and improvement. It encourages community participation, bug reporting, and feature requests.

Overall, Read the Docs simplifies the process of hosting and maintaining documentation for software projects. By automating the documentation build process and providing a user-friendly hosting platform, it enables developers to focus on creating high-quality documentation that is easily accessible to their project's users and contributors.

Sphinx

https://github.com/sphinx-doc/sphinx

Sphinx is a widely used documentation generation tool that is popular among developers, particularly in the Python community. It was initially created to document the Python programming language itself, but it has since been adopted for various other projects and programming languages.

Here are some key features and characteristics of Sphinx:

1. Markup Language: Sphinx uses reStructuredText as its default markup language. reStructuredText is a lightweight and easy-to-read markup language that allows for structuring content and adding formatting elements.

2. Documentation Structure: Sphinx organizes documentation into a hierarchy of files and directories. It follows a modular approach where documentation is divided into individual topics or sections, making it easy to manage and update specific parts of the documentation.

3. Automatic Indexing and Cross-Referencing: Sphinx automatically generates an index and cross-references within the documentation, making it easy to navigate and link different sections together. It provides support for creating tables of contents, footnotes, references, and citations.

4. Code Documentation: Sphinx integrates well with code documentation tools like Python's docstrings and can automatically extract and incorporate documentation from the source code. This makes it convenient to keep code and documentation in sync.

5. Output Formats: Sphinx supports generating documentation in various output formats, including HTML, PDF, ePub, and plain text. This flexibility allows developers to publish their documentation in different formats suitable for web-based browsing, printing, or e-book reading.

6. Themes and Customization: Sphinx provides customizable themes that control the appearance and layout of the generated documentation. Developers can choose from pre-built themes or create their own to match the project's branding and style.

7. Extensions and Plugins: Sphinx offers a rich ecosystem of extensions and plugins that enhance its functionality. These extensions provide additional features like automatic API documentation generation, support for mathematical formulas, integration with version control systems, and more.

8. Localization and Internationalization: Sphinx supports localization and internationalization, allowing documentation to be translated into multiple languages. This feature is beneficial for projects with a global user base.

9. Integration with Version Control: Sphinx integrates well with version control systems like Git, enabling documentation to be easily versioned and tracked alongside the codebase. It simplifies collaboration and allows teams to maintain documentation in sync with code changes.

10. Community and Active Development: Sphinx has a vibrant and active community of developers contributing to its development and maintenance. It is an open-source project, which means it is continuously evolving and improving based on community feedback and contributions.

Overall, Sphinx provides a powerful and flexible documentation generation solution that simplifies the process of creating and maintaining project documentation, particularly for software projects.

[lukefretwell]

@curtismchale seems like RTD has more of a following than Sphinx, so I'd lean towards that.

[curtismchale]

@lukefretwell

I've done some more research on the options. RTD is simply a docs hosting solution. To use it we still need to use Sphinx or MkDocs to actually write/build the docs. To use RTD and have a private repository/private docs we would need to pay $50/month for RTD. We could use RTD to host multiple repositories of documentation if we want on the same domain. If we want custom domains for our docs then the cost is $150/month.

Sphinx has some GitHub integrations we could use to publish to GitHub Pages. We may be able to password-protect those pages, but it's a bit of a hack so a user could bypass it if they wanted to. I think that Gitlab pages would let us do the same build for free and they have access control on their pages product that would let us only allow specific Gitlab users to view the site. The final option that looks viable is to publish the docs to our current Google infrastructure. I've found some resources that make me think we can password-protect a Sphinx project on our Google infrastructure.

It doesn't appear that Sphinx has a web editor GUI so it would need to be worked on in a local code editor and pushed to the repository. This may only matter if we want Kevin to edit the docs.

From a cost perspective building Sphinx ourselves and hosting it on our Google Infrastructure is a better option. It will cost more to get it set up, but then far less as we use the solution more.

If you want to see my personal notes with links to some of the resources that lead me to the conclusions above they are here.

Questions

• Do we care if our docs are publicly available? I think we probably do for the internal docs we're talking about that may have links to internally sensitive things.
• Does the lack of GUI editing matter?