networkx
New article: The good will hunting problem
Something I've been working on this weekend after a recent movie night!
I haven't done a copy-edit pass and there's still some formatting things to fix up, but feedback on high-level content and organization is most welcome!
Marking as draft for now as I don't want to subject anyone to the text until I've had a chance to apply some polish.
Okay, I had a chance to proofread so I think this is ready for another set of eyes!
Here's a link to the rendered article: https://output.circle-artifacts.com/output/job/62a352da-a6b6-49bc-a08d-e7551a27541e/artifacts/0/site/_build/html/content/applications/goodwillhunting.html
Meta-review question: I reviewed this by just looking at the md file text and ignoring whitespace, quotes etc. Should I also be converting it to a notebook locally and running that? And are there linting issues I should worry about? Some lines were definitely longer while others are wrapped.
Great question! In principle there are three "documents" involved - one "source" document (the .md file) and two "target" documents that are rendered from the source - a jupyter notebook and an html page. The typical review process only deals with the source .md file and the rendered html, which can be viewed with the circleci artifact link. What I typically do is open these side by side: markdown file in a text editor on the left half of the screen, and rendered html open in a browser on the right half. This makes it easy to map the patterns in the source file to the rendered output.
Notice that this review process ignores the third "output" - the jupyter notebook. That doesn't necessarily have to be the case! The .md file is actually a text-based jupyter notebook that is directly open-able via e.g. jupyter lab (albeit with jupytext and the juyterlab-myst extensions installed). Personally I never worry about the notebook rendering explicitly, but that's because I'm much more comfortable authoring in markdown than through jupyterlab. My personal takeaway is: anything that renders correctly in html will render fine in jupyter lab too[^1], so no need to explicitly check both.
Finally re: linting/testing - we do run linting on the code cells automatically via pre-commit, so no need to explicitly worry about that. It's a good point about white space/line wrapping - we don't currently lint the markdown so that can get a little ugly (especially with long URLs etc.). This is apparent in the other notebooks, which tend not to have line breaks at all. So I'd call this a "known issue" as well and something that we should try to handle automatically so that reviewers don't have to explicitly think about markdown formatting either. AFAIK there is no specific linting tool for MyST-markdown, but hopefully standard tooling like prettify can at least help with things like line length. I will open an issue about this, thanks for bringing it up!
[^1]: In practice there is not complete feature parity between the html-generation engine and the jupyter notebook rendering engine... this is a known limitation and something that underyling projects like myst-md are working to improve. If you're really interested, check out the https://github.com/scientific-python/executable-tutorials repo for extensive details and discussions related to the underlying tooling!