Improve consistency

[20kavishs]

In the NetworkX community meeting this week (on 3/21/23) I asked about high priority improvements for nx-guides.

@rossbar mentioned making the notebooks more consistent for a start

I standardized the notebooks by doing the following (this is my first contribution, so wanted to start small!)

• Added an 'Import packages' cell with imports to the top of each notebook
• Added a 'References' cell at the bottom of each notebook
• Cleaned up citations
• Made introductions to the notebook more similar and convenient (i.e. added hyperlinks to part of NetworkX used)
• Added code comments where they were missing

Any other consistency fixes?

[20kavishs]

Also as a side note...should we rename (and change the wording in) the Euler's Algorithm notebook to be about Eulerian paths and circuits? I don't think there is an explicit "Euclid's algorithm"...it's mostly about Eulerian paths and circuits and how to find them.

Just a small semantic issue, I can take care of it quickly if it is a good idea.

Also...any insight on how to pass the build-docs checks? Looking at the failing tests, they seem to be quite odd (i.e. that 2 == 3).

[navyagarwal]

@20kavishs

Hey, I wanted to drop in a couple of suggestions that might help with making the guides more consistent in the long run -

1. Having a template notebook that contains the required sections for each guide like references, a standard introduction with links to Networkx docs, imports etc.
2. Having a guidelines document that lists the recommended practices for notebooks like adding code comments, using the Networkx vocabulary for certain keywords etc.
3. We can link both these documents to a contributing guide

[20kavishs]

@navyagarwal

Good ideas, thanks for your thoughts!

I think the template notebook might be a bit much as of now...I feel that it might clutter nx-guides. I like the other two points though.

Instead of making a new guidelines document, we can just add a section to the contributor's guide already made by @dtekinoglu #81. This way potential contributors can just refer to one document.

I'm working on it right now

Edit: I put it in PR #99

@rossbar @MridulS

[rossbar]

Thanks for this @20kavishs - on the whole I do think this gives the nx-guides a more cohesive feel. In particular, I think moving all the imports to the top of the tutorials in their own section is an improvement.

There are a few things that need to be worked out re: duplicated references and a couple changes that will break formatting - see inline comments below.

Note also that I took the liberty of pushing up a few minor changes, so be sure to git pull before making your next push!

[20kavishs]

Resolved suggestions and added import packages and references section to LCA notebook, thanks for the feedback! @rossbar @MridulS

[dschult]

The animations don't seem to animate on the html pages. I guess that they do for the JupyterLab interface through. @MridulS and @rossbar do you expect animations to not show on the html pages?

I have mostly picky grammar/spelling/wording suggestions below. Some of the more major changes involve changing the pseudocode so it is essentially written in python. (Python is often as good as pseudocode.)

Changes I didn't make, but I think should be made (feel free to push back though):

• change all "vertex/vertices" to "node/nodes"
• use "we" instead of "I" to imply the reader is working through this with the writer as they read.
• Is the recursive version of the algorithm instructive (gives the user some intuition)? If so, maybe some more words about the intuition gained from reading it. As it is, the recursive part seems like a distraction with almost no text describing why it is presented (and why only for DFS).

[20kavishs]

Addressed feedback from @dschult, thank you!

I'm struggling a bit with making the CI happy. Pre-commit tests are passing, but the nbval tests are not.

pytest --nbval-lax --durations=25 content/ is not collecting any tests for some reason, and I'm having the same issue locally.

Any thoughts on how to help the CI? @MridulS @rossbar @dschult

[rossbar]

Unfortunately I think merging the traversal notebook into this PR has overloaded things as now there's a whole new notebook to review! <soapbox>Generally speaking, it's preferable to keep PRs limited in scope so that unrelated changes don't become blockers</soapbox>

IMO the "consistency" changes are ready to go, but I haven't had a chance to look over traversal yet. There are a couple ways this could move forward:

1. Move HEAD for this PR back to d02c17e and merge it, creating a separate PR for the traversal notebook.
2. Leave everything together and wait for review of the traversal notebook. Alternatively, if the traversal notebook looks close enough to ready to other reviewers, we could get it in and fix it after the fact. The non-rendered animations gives me pause, but I defer to other reviewers!

My preference is for option 1. If you decided to go that route, it would look something like:

git checkout improveConsistency
git pull  # Make sure local HEAD points to the latest commit (70130c8)
git checkout -b add-traversal-notebook  # Create a new branch here (you now have 2 branches pointing to the same commit)
git checkout d02c17e  # Go back to the last commit related only to consistency changes
git branch -D improveConsistency  # Delete the former branch...
git checkout -b improveConsistency  # ...and re-attach it to d02c17e
git push --force  # Move the PR back to d02c17e
# Then create a new PR for traversal (all history etc. preserved)
git checkout add-traversal-notebook
git push -u origin add-traversal-notebook  # Then create the PR on GH

[20kavishs]

I'll aim for option 1, if the other reviewers agree?

[dschult]

Yes -- let's go ahead and separate these two parts of this PR.

[dschult]

OK.. I think this improve consistency PR is ready for review.
The traversal has been separated and the notebook tests are working.

[rossbar]

LGTM, thanks @20kavishs !