Open goodboy opened 4 years ago
The readme update in #163 also mentions maybe adding some diagrams for both messaging / protocols docs and supervision trees stuff:
add some process tree diagrams using both something like mermaid.io and output from
pstree
?
There was a project i saw recently that had a sphinx theme I really loved; too bad can't find it again.
It had the automatic toc arrows pointing to the section on the left as you scrolled down the page.
I'm not sure, but I've seen a couple projects using https://sphinx-book-theme.readthedocs.io/en/latest/, and I rather like it. Was thinking about using it for some internal documentation at work.
@ryanhiebert oh nice! Yeah this is definitely getting closer.
I'm looking for a very simple black and white theme and a nice big logo. This is one of the closest I've seen šš¼
Looks to be based on the pydata themes.
Damn, they made pandas docs look good.
So sphinx-book-theme
turns out to be the same one that ray
uses.
I like a lot about it but think it could be simplified a bit to fit the style I've got envisioned for this project.
I've created executablebooks/sphinx-book-theme#296 which seems to so far be well received š„³
Summary:
I've pushed up some draft changes on https://github.com/goodboy/tractor/tree/new_docs_polish
Made https://github.com/executablebooks/sphinx-book-theme/issues/365 to address missing logo stuff.
@Fuyukai also mentioned in chat that our github badge link is borked šæ
as per msgspec
docs, apparently the hip new minimalist theme is this bby:
https://github.com/pradyunsg/furo
Also learned about mkdocs the other day which apparently has sphinx
compat inventory generation?
Our docs are terrible and outdated.. ya we know :joy:
Yes you can find that terrible version (at time of writing) here:
sphinx themes I'm thinking we should use:
These are the hot ones I've found really lovely to read in python (related) land:
general theme tips:
[ ] obviously the
sphinx_docs_theme
which I've already opened issues on ages ago..[ ]
msgspec
with its use offuro
:[ ]
ray
with it's similar theme: https://docs.ray.io/en/latest/ray-core/walkthrough.htmlsphinx_book_theme
: https://github.com/ray-project/ray/blob/master/doc/source/conf.py#L263 (like i originally mentioned in this issue..[ ]
polars
' user guide: https://pola-rs.github.io/polars-book/user-guide/index.htmlpydata_
theme I guess: https://github.com/pola-rs/polars/blob/main/py-polars/docs/source/conf.py#L79[ ]
pandas
also using thepydata
theme:Diagramming frameworks
Once we've settled on a (better) theme we need to add a ton of diagrams with something that can embed in RST ideally, though we might have to do some automation to just generate using some other tools?
mermaid
seems the obvious answer but it's markdown only AFAIK:general docs:
https://github.com/mermaid-js/mermaid
https://stackoverflow.com/questions/50762662/how-to-install-mermaid-to-render-flowcharts-in-markdown
https://mermaid.js.org/syntax/examples.html
CLI editor B)
https://github.com/mermaid-js/mermaid-cli
[ ] maybe TODO: hook this up with xonsh, maybe make a xontrib?
online editor!
https://mermaid-js.github.io/mermaid-live-editor/edit/#pako:eNplj00KwjAQha8SZpOF9QJZdKUncBsoYzJqaPNjmoCl9O6mJAjFWQzDe9-DNysorwkEzPTO5BRdDD4jWulYmYAxGWUCusTIznqgD6lh8j78-_foR4q6GnUfI-e-PzVIsJWjSsY7Lhi_54VvNdH8HT2GC4Zq5JWCDixFi0aX4uuuSUgvsiRBlFNjHCVItxUuB42JrtokH0E8cJqpA8zJ3xanfkKl2utN3b7EcGB3
example from piker emsd order msg flow: https://mermaid-js.github.io/mermaid-live-editor/edit/#pako:eNqVk11PwyAUhv8K4YYZq-k0xoXEJX5de7HbXozBmZJR2h2oUZv9d-lKXddlOrmgcHre53wANZWFAsqpg3UFVsKTFq8o8sySMEqBXktdCuuJNBqsP7RD7tShdYHFCjD-aOcWcDGdnjcSTl5QAY7qErUETq7TMBLi9FfYpJfpOCHwAZITZvQ7sISwQisWtreL8QSu5puzltqwGmYMyMlDu4h0tsWzHz5rArAuwhFmZO1Sjcx7uRrVQbJTJARh3TOwYVpt0Zz8Q3os-swLX7lRbUUeWsSW2hjWa1h6cyx2J0Rw5a_C4Qk9inAhzCDvvxrfifarm59andt-75jcYgwoNmzU_MQ6-4Riv9E0oTlgLrQKN79uaBn1b5BDRnlYKoGrjGZ2E_yqUgkPz0r7AilfCuMgoaLyxezTSso9VtA5xacTvTbfCPwRJg
which renders to
obsidian
integrations:https://github.com/dartungar/obsidian-mermaid
https://heymichellemac.com/knowledge-management-flow-diagram-in-obsidian
Pikchr: a PIC-like markup language for diagrams in technical documentation. -> looks decent but not sure if it's too niche?
Docs frameworks
Alts and/or extensions to
sphinx
worth a shot?mkdocs
which apparently hassphinx
inventory compat now?Content/section IDEAS
Now that #129 is about to land we need some sections on:
[ ] using the debugger in a variety of process tree configurations
.breakpoint()
and the crash handler systempytest
's--pdb
even with just plain old process local tasks[ ] adjustment of all examples to drop use of namespace prefixes when calling
Portal.run()
andActorNursery.run_in_actor()
once a fix for #69 lands[ ] re-org all major sections into new pages, a rough outline might look like:
[ ] pretty up the readme including #153
[ ] a stylistic change would be good where we introduce the project as something like *trio-across-processes
and/or a next-gen
multiprocessing`:mp
data structures[ ] there was an existing issue RE a streaming example: https://github.com/goodboy/tractor/issues/114#issuecomment-695328274