Skip to content

[pyos][examples] Organization of notebook examples #408

Open
@sneakers-the-rat

Description

@sneakers-the-rat

I'll gather some thoughts on organization of the notebook examples that aren't bugs but style and readability suggestions here, rather than opening several issues:

Global Structure

  • It's not really clear to me if there is some intended order for these notebooks, and they seem to have mixed purpose: some basic syntax demos, some higher-level application examples, and what looks like a conference/workshop demo. I would suggest either structuring these by embedding them in the docs/linking to them from the docs with some explanation (links from the relevant sections of the API docs would also be nice, haven't looked to see if that exists yet). You might also consider subdirectories for different types of notebooks.

Specific Notebooks

Pagerank

  • I am inferring the pagerank demo is intended as the introductory example from the "getting started" docs. It currently mixes some examples of basic syntax with the pagerank implementation itself, which is unclear - the example starts abruptly at "Compare with C" in this version without introduction, and the graph that was being used as an example in the first half is then changed to a binary graph. recommendation: split basic syntax into its own graph, either copy some of the description of the demo from the docs and link to it from that point in the docs (which would put it in two places, which might be less desirable), or, preferably, move the whole example + description to the notebook and embed in docs.
  • Some narration and inline comments would help the pagerank demo a lot: eg. a larger graph is constructed with networkx and then converted to graphblas format - that's a nice feature, and highlights the relationship with networkx: that it can be used for some utility tasks that you can then move back and forth with graphblas. It would be worth commenting on that and potentially linking out to the other i/o functions in the API docs from there.

pausing here for now, will edit any additional comments on example structure in here

Related to: pyOpenSci/software-submission#81

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprove or add to documentationhygieneImprove code quality and reduce maintenance overhead

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      pFad - Phonifier reborn

      Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

      Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


      Alternative Proxies:

      Alternative Proxy

      pFad Proxy

      pFad v3 Proxy

      pFad v4 Proxy