[Carwyn Pelley (cpelley)]

Direct link to new README.md
Direct link to new FAQ.md
Direct link to new demo.ipynb

---

Detailed changes

• Added additional logo variants that include the project name, making them easier to use both within and outside the project.
  • I will potentially turn text into svg paths in a future change since that is more consistent across platforms.
• Added an FAQ file covering common misconceptions about DAGrunner, including what it is, what it is not etc.
• Made a further pass at clarifying the opening description of DAGrunner.
• Clarified how the reference documentation is generated and added documentation describing the contents of the docs/ directory. This was a point of confusion clear in a previous contribution someone was trying to make.
• Significantly expanded the Jupyter demonstration notebook with two examples:
  • A truly minimal example with no concepts such as lead times, where node identities are represented in their simplest form: plain strings.
    • Included a small change to _get_networkx so DAGrunner can handle graphs containing string nodes when constructing a NetworkX graph. Whilst we recommend users explicitly define and supply a NetworkX graph, anything suitable for supplying NetworkX should also be supported by DAGrunner's graph construction utilities.
      • I have added a unittest accordingly. Whilst this isn't ideal for a private function, I'm making an exception in this case as we don't want users to think the _gen_networkx is part of the supported UI.
  • A more realistic example (the pre-existing example from the notebook) using an immutable Node dataclass to represent node identities, demonstrating graph branching and execution, with the final result produced by concatenating node identifier strings.
• Documented the docs/gen_docs script used to generate the reference documentation and updated it to use argparse.

[Carwyn Pelley (cpelley)]

Hey Joshua Wiggs (@JoshuaWiggs), Stephen Moseley (@MoseleyS), bayliffe, Paul Abernethy (@PaulAbernethy). This is another attempt to clear-up issues around what DAGrunner is and is not.
I would very grateful for your feedback and whether you feel this provides sufficient clarity. Please feel free to limit your review to this particular issue (principally README.md and the new FAQ.md, linked to in the PR description). Note that Copilot heavily helped me come up with many of the questions and answers in the FAQ by rummaging through emails and teams chats to me.

bayliffe, you may take a particular interest to the updated ipython notebook I'm sure. Again, I have linked directly to this in the PR description.

Cheers

[Copilot]

🟡 Changes recommended

There are correctness issues in the new documentation example (FAQ) and a real runtime risk in _get_networkx due to list(nodes.keys())[0] on empty input, both of which should be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates DAGrunner’s external-facing documentation and assets, expands the demo notebook, and makes a small compatibility change to graph construction so tuple-based graphs with string node IDs can be converted into a NetworkX DiGraph.

Changes:

• Refresh README messaging, add an FAQ, and document the docs/ directory and doc-generation script.
• Expand docs/demo.ipynb with a minimal string-node example plus a more realistic dataclass-node example.
• Update _get_networkx behavior and add unit tests to support tuple-based graphs whose node IDs may be strings.

File summaries

File	Description
README.md	Updates project overview and documentation pointers; adds logo table and reorganizes sections.
FAQ.md	Adds new FAQ content, including a quick-start execution example.
docs/README.md	Documents what lives under docs/ (reference docs + logos).
docs/logo_wtitle.svg	Adds a color logo variant with the project title text.
docs/logo_title.svg	Adds a standalone title SVG for the project name.
docs/logo_bw_wtitle.svg	Adds a black-and-white logo variant with the project title text.
docs/gen_docs	Updates the reference-doc generator script to use argparse and improves its docstring.
docs/demo.ipynb	Significantly expands the demo notebook and adds new examples and narrative.
dagrunner/tests/execute_graph/test__gen_networkx.py	Adds tests covering _get_networkx behavior for tuple-based graphs and different input types.
dagrunner/execute_graph.py	Adjusts _get_networkx tuple-handling to better support string node IDs.

Review details

Suppressed comments (1)

docs/gen_docs:30

• The argument names in the example docstring should match the corrected signature (arg1, kwarg1).

    - `args1` (str):
      Some positional argument.
    - `keywarg1` (int, optional):
      Some keyword argument with a default value.

• Files reviewed: 6/10 changed files
• Comments generated: 8
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Stephen Moseley (MoseleyS)]

This is really good. Thanks Carwyn.

Is this the right place to add some docs on handling exceptions and skipping parts of a graph? The docs might already exist in which case they just need linking to.

[Stephen Moseley (MoseleyS)]

Can this abscissa be removed or populated now?

[Carwyn Pelley (cpelley)]

I have now removed the example from the FAQ in favour of what's in the ipython notebook if that's what you mean?