> Please don’t write your documentation in Markdown. Please. I’m begging you.

> Markdown is tolerable for short documentation, like a readme.md. Past that, it’s the wrong tool for the job.

A very good #rant about markdown issues. Provides several solutions as well.

#docops

​​This is a GitHub Action to generate TOC (Table of Contents), which executes DocToc and commits if changed.

https://github.com/technote-space/toc-generator

#docops

​​Kroki provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), C4 (with PlantUML), Ditaa, Erd, GraphViz, Mermaid, Nomnoml, PlantUML, SvgBob, UMLet, Vega, Vega-Lite, WaveDrom... and more to come!

So, you can represent any diagram as a HTTP request.

https://kroki.io/

Example: https://kroki.io/plantuml/svg/eNplj0FvwjAMhe_5FVZP40CgaNMuUGkcdttp3Kc0NSVq4lRxGNKm_fe1HULuuD37-bOfuXPUm2QChEjRnlIMCDmdUfHNSYY6xh42a9Fsegflk-yYlOLlcHK2I2SGtX4WZm9sZ1o8uOzxxbuWAlIGj8cshs6M1jDuY2owyU2P8jAezdnn10j53X0hlBsZFW021Pq7HaVSNw-KN-OogG8F8BAGqT8dXhZjxW4cyJEW6kcC-yHWFagHqW0MfaThhYmaVyE26P_x27qaDmXeruqqAMMw1h-ZlRI4aF3dX7hOwm5XzfIKDctlNcshPT1tFa8JPYAj-Zf5F065sqM=

#docops #java #python

​​Contextualise is a simple and flexible tool particularly suited for organising information-heavy projects and activities consisting of unstructured and widely diverse data and information resources -- think of investigative journalism, personal and professional research projects, world building (for books, movies or computer games) and many kinds of hobbies.

> On a side note, an alpha version of Contextualise is already available at https://contextualise.dev. It is not advised, at this stage, to use Contextualise for anything other than testing purposes. Data could be irrevocably lost!

https://github.com/brettkromkamp/contextualise

#python #docops

​​interrogate checks your code base for missing docstrings.

Documentation should be as important as code itself. And it should live within code. #python standardized docstrings, allowing for developers to navigate libraries as simply as calling help() on objects, and with powerful tools like Sphinx, pydoc, and Docutils to automatically generate HTML, LaTeX, PDFs, etc.

interrogate will tell you which methods, functions, classes, and modules have docstrings, and which do not. Use interrogate to:

- Get an understanding of how well your code is documented;
- Add it to CI/CD checks to enforce documentation on newly-added code;
- Assess a new code base for (one aspect of) code quality and maintainability.

Let’s get started!

https://interrogate.readthedocs.io/en/latest/

Personal opinion: I really like the incremental addoption feature.

#docops

A Gatsby theme for creating Primer documentation sites.

Doctocat makes it easy to set up a documentation site so you can focus on what's important: writing docs. You can start with just several clicks.

Made by GitHub.

https://primer.style/doctocat/getting-started

#js #react #docops

​​This extension integrates Draw.io into #vscode

Features
- Edit .drawio or .dio files in the Draw.io editor, as xml or both.
- Edit .drawio.svg files with embedded Draw.io diagrams (might be slow for diagrams with > 400 nodes).
- To create a new diagram, simply create an empty .drawio or .drawio.svg file and open it!
.drawio.svg are valid .svg files.
- Uses an offline version of Draw.io by default.
- An online Draw.io url can be configured.
- A Draw.io theme can be selected.

https://github.com/hediet/vscode-drawio

#ts #docops

​​Great Expectations: Always know what to expect from your data.

Great Expectations helps data teams eliminate pipeline debt, through data testing, documentation, and profiling.

Software developers have long known that testing and documentation are essential for managing complex codebases. Great Expectations brings the same confidence, integrity, and acceleration to data science and data engineering teams.

See Down with Pipeline Debt! for an introduction to the philosophy of pipeline testing: https://medium.com/@expectgreatdata/down-with-pipeline-debt-introducing-great-expectations-862ddc46782a

Key features:
- Expectations or assertions for data. They are the workhorse abstraction in Great Expectations, covering all kinds of common data issues
- Batteries-included data validation
- Tests are docs and docs are tests: many data teams struggle to maintain up-to-date data documentation. Great Expectations solves this problem by rendering Expectations directly into clean, human-readable documentation
- Automated data profiling: wouldn't it be great if your tests could write themselves? Run your data through one of Great Expectations' data profilers and it will automatically generate Expectations and data documentation
- Pluggable and extensible

https://github.com/great-expectations/great_expectations

#python #ds #docops

​​A next-generation curated knowledge sharing platform for data scientists and other technical professions.

The Knowledge Repo project is focused on facilitating the sharing of knowledge between data scientists and other technical roles using data formats and tools that make sense in these professions. It provides various data stores (and utilities to manage them) for "knowledge posts", with a particular focus on notebooks (R Markdown and Jupyter / IPython Notebook) to better promote reproducible research.

For more information about the motivation and inspiration behind this project, we encourage you to read our Medium Post: https://medium.com/airbnb-engineering/scaling-knowledge-at-airbnb-875d73eff091

https://github.com/airbnb/knowledge-repo

#python #ds #docops

​​Foam is a personal knowledge management and sharing system, built on Visual Studio Code and GitHub.

You can use Foam for organising your research, keeping re-discoverable notes, writing long-form content and, optionally, publishing it to the web. Foam is extremely extensible to suit your personal workflow. You own the information you create with Foam, and you’re free to share it, and collaborate on it with anyone you want.

Features:

- The editing experience of Foam is powered by VS Code, enhanced by workspace settings that glue together Recommended Extensions and preferences optimised for writing and navigating information.
- To back up, collaborate on and share your content between devices, Foam pairs well with GitHub.
- To publish your content, you can set it up to publish to GitHub Pages with zero code and zero config, or to any website hosting platform like Netlify or Vercel.

https://foambubble.github.io/foam/

#ts #docops #vscode