Simplify writing_docs to just one md file (#1254)

* move, no fixed links

* fix renamed references

* add missing assets

* fix doclink tests

* Update docs/usage/README.md

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

* -

---------

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: Ivan Nikolic <lesh@sysphere.org>

Author: 3 people

README.md

@@ -241,8 +241,8 @@ DimOS comes with a number of monitoring tools:
 # Documentation
 
 Concepts:
-- [Modules](/docs/concepts/modules.md): The building blocks of DimOS, modules run in parallel and are singleton python classes.
-- [Streams](/docs/api/sensor_streams/index.md): How modules communicate, a Pub / Sub system.
+- [Modules](/docs/usage/modules.md): The building blocks of DimOS, modules run in parallel and are singleton python classes.
+- [Streams](/docs/usage/sensor_streams/index.md): How modules communicate, a Pub / Sub system.
 - [Blueprints](/dimos/core/README_BLUEPRINTS.md): a way to group modules together and define their connections to each other.
 - [RPC](/dimos/core/README_BLUEPRINTS.md#calling-the-methods-of-other-modules): how one module can call a method on another module (arguments get serialized to JSON-like binary data).
 - [Skills](/dimos/core/README_BLUEPRINTS.md#defining-skills): An RPC function, except it can be called by an AI agent (a tool for an AI).

dimos/utils/docs/doclinks.py

@@ -106,8 +106,8 @@ def build_doc_index(root: Path) -> dict[str, list[Path]]:
     """
     Build an index mapping lowercase doc names to .md file paths.
 
-    For docs/concepts/modules.md, creates entry:
-    - "modules" -> [Path("docs/concepts/modules.md")]
+    For docs/usage/modules.md, creates entry:
+    - "modules" -> [Path("docs/usage/modules.md")]
 
     Also indexes directory index files:
     - "modules" -> [Path("docs/modules/index.md")] (if modules/index.md exists)

dimos/utils/docs/test_doclinks.py

@@ -256,7 +256,7 @@ def test_github_mode(self, file_index):
     def test_relative_mode(self, file_index):
         """Should generate relative paths in relative mode."""
         content = "See [`service/spec.py`]()"
-        doc_path = REPO_ROOT / "docs/concepts/test.md"
+        doc_path = REPO_ROOT / "docs/usage/test.md"
 
         new_content, _changes, _errors = process_markdown(
             content,
@@ -350,7 +350,7 @@ def test_doc_link_github_mode(self, file_index, doc_index):
     def test_doc_link_relative_mode(self, file_index, doc_index):
         """Should generate relative paths for doc links."""
         content = "See [Blueprints](.md)"
-        doc_path = REPO_ROOT / "docs/api/test.md"
+        doc_path = REPO_ROOT / "docs/usage/test.md"
 
         new_content, _changes, errors = process_markdown(
             content,
@@ -364,8 +364,8 @@ def test_doc_link_relative_mode(self, file_index, doc_index):
         )
 
         assert len(errors) == 0
-        # Should be relative path from docs/concepts/ to docs/
-        assert "../" in new_content
+        # Should be relative path from docs/usage/ to target doc
+        assert "[Blueprints](blueprints.md)" in new_content
 
     def test_doc_not_found_error(self, file_index, doc_index):
         """Should error when doc doesn't exist."""

docs/api/README.md

@@ -293,7 +293,7 @@ You can enable a tag by selecting -m <tag_name> - these are configured in `./pyp
 - Open the PR against the `dev` branch (not `main`).
 - **No matter what, provide a few-lines that, when run, let a reviewer test the feature you added** (assuming you changed functional python code).
 - Less changed files = better.
-- If you're writing documentation, see [writing docs](/docs/development/writing_docs/README.md)
+- If you're writing documentation, see [writing docs](/docs/development/writing_docs.md)
 - If you get mypy errors, please fix them. Don't just add # type: ignore. Please first understand why mypy is complaining and try to fix it. It's only okay to ignore if the issue cannot be fixed.
 - If you made a change that is likely going to involve a debate, open the github UI and add a graphical comment on that code. Justify your choice and explain downsides of alternatives.
 - We don't require 100% test coverage, but if you're making a PR of notable python changes you should probably either have unit tests or good reason why not (ex: visualization stuff is hard to test so we don't).

docs/concepts/README.md

@@ -143,5 +143,5 @@ Install Foxglove from:
 - **Skills** are callable methods (decorated with `@skill`) on any `Module`, automatically discovered by agents.
 
 Reference:
-- Modules overview: `/docs/concepts/modules.md`
-- TF fundamentals: `/docs/api/transforms.md`
+- Modules overview: `/docs/usage/modules.md`
+- TF fundamentals: `/docs/usage/transforms.md`

docs/development/README.md

@@ -0,0 +1,7 @@
+# Writing Docs
+
+1. Where to put your docs:
+    - If it only matters to people who contribute to dimos (like this doc), put them in `docs/development`
+    - Otherwise put them in `docs/usage`
+2. Run `bin/gen_diagrams` to generate the svg's for your diagrams. We use [pikchr](https://pikchr.org/home/doc/trunk/doc/userman.md) as a diagram language.
+3. Use [md-babel-py](https://github.com/leshy/md-babel-py/) (`md-babel-py run thing.md`) to make sure your code examples work.