W to g guide

[sjsrey]

This is a start towards addressing #712. Seeking feedback and discussion.

It will add a note to the index page:

This also adds a dynamically generated rst file that will report on the members for W and Graph, which is the target of the note.

In addition, I will add a notebook that builds on the suggestions in #712 to have more of a user facing orientation.

This is intended to be dynamic and assist us as we fully build out the Graph moving forward.

Once we are done with the transition, we can remove this dynamically generated rst file, if so desired.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 85.3%. Comparing base (c97bf87) to head (8c0bc1f). Report is 1 commits behind head on main.

Additional details and impacted files

@@          Coverage Diff          @@
##            main    #733   +/-   ##
=====================================
  Coverage   85.3%   85.3%           
=====================================
  Files        149     149           
  Lines      15914   15914           
=====================================
  Hits       13580   13580           
  Misses      2334    2334           

[knaaptime]

sweet

[martinfleis]

I like that automatic comparison but in some cases, it may be worth adding a note explaining why there's no match and what is recommended to do instead. E.g Graph does not have islands but has isolates instead etc.

I also suppose that merge shall wait until the notebook is complete, right?

[sjsrey]

I like that automatic comparison but in some cases, it may be worth adding a note explaining why there's no match and what is recommended to do instead. E.g Graph does not have islands but has isolates instead etc.

Yes, this was intended to identify all the cases we need to surface in the recommendations. I wasn't sure if we should put the recommendations in these tables, or treat them in the migration notebook where we can have a bit more narrative for the user.

I also suppose that merge shall wait until the notebook is complete, right?

Definitely.

[martinfleis]

treat them in the migration notebook where we can have a bit more narrative for the user.

That may be better. We just need to make a link to the notebook clear and visible from the RST with the tables.

[sjsrey]

This is still WIP. I have split the migration material and member comparisons apart for different audiences (users,devs). This also reorganizes the notebooks and changes the tutorial to a user-guide.

The idea is to keep the component comparison around to automatically generate the W-G tables. These will get updated each time the docs are built.

Meanwhile, the user migration guide is a notebook that can now be fleshed out for the current state of the Graph. docs/user-guide/graph/w_g_migration.ipynb which can now be updated.

Although I say WIP as I want to finish the migration notebook now that the latest changes to the graph have been merged. I think we may want to merge to double check all the doc links are working properly. They do work locally, but some of the new links are to new files in his pr that will live in upstream?