Enhance documentation with book-level narrative and domain case studies

[Copilot]

Transforms py3plex docs from API reference notes into a pedagogical guide with richer narrative, worked examples, and interpretation guidance for researchers new to multilayer networks.

Changes

Getting Started

• Added scenario-driven quickstart ("friends and colleagues" example)
• Tutorial now includes story opening, goal sentences per section, and "how to write this in a paper" narration
• "What you learned" summaries with core mental model (node-layer pairs, layers as contexts)

Concepts

• Multilayer Networks 101: Toy examples for each network type, "What Goes Wrong When You Flatten" section, modeling decision checklist, domain-specific examples (bio/social/transport/academic)
• Core Model: Numeric supra-adjacency example (3 nodes × 2 layers), memory implications, NetworkX internals, design trade-offs vs alternatives

User Guide

• Community Detection: Single vs multilayer conceptual differences, parameter tuning cookbook (γ/ω), failure diagnosis, mini case studies
• Random Walks: Complete 6-step embedding workflow, p/q parameter effect tables, failure modes (disconnected graphs, skewed degrees, memory)

New Chapter: Case Studies

• 4 end-to-end domain examples with problem context, data modeling decisions, complete code, interpretation, and adaptation templates:
  • Multilayer PPI with evidence types
  • Cross-platform social network influence
  • Urban transportation resilience
  • Heterogeneous academic networks

Example Addition

Before (bare code):

network.basic_stats()

After (with interpretation):

network.basic_stats() # Output shows 6 nodes but 4 unique IDs—Alice and Bob appear in both layers. # This distinction is fundamental: node-layer pairs vs entity count.

All existing code examples preserved. Sphinx build passes.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>binding text for pdf docs</issue_title>
<issue_description>

You are helping me turn the py3plex documentation into a polished, book-level guide.

Context:

• Project: py3plex – a Python toolkit for visualization and analysis of multilayer and multiplex networks.
• Target audience: researchers and practitioners in network science, complex systems, computational biology, social network analysis, infrastructure/transportation modeling, and applied ML on graphs.
• Current docs already contain: a 5-Minute Quickstart, 10-Minute Tutorial, Installation and Setup, Multilayer Networks 101, Core Model, Design Principles, Algorithm Landscape, Working with Networks, Network Statistics, Community Detection, Random Walks, etc.
• Problem: the docs are technically correct but read as API/tutorial notes. I want book-level narrative, more context, and richer, story-like explanations that connect theory, implementation, and real-world use cases.

Your job:
Expand and rewrite the existing documentation so it reads like a short technical book (~8–12 chapters), while keeping all APIs and code examples correct and up to date. Preserve the current structure and section titles where possible, but enrich them heavily and add new sections where helpful. Prefer clear, precise, pedagogical writing with lots of “why” and “when” explanations, not just “how”.

General style guidelines:

• Tone: clear, confident, researcher-friendly, slightly opinionated when giving best practices, but never hypey.
• Depth: assume readers know Python and basic graph theory, but not multilayer networks. Explain concepts with intuition, small examples, and only as much math as needed.
• Structure: each chapter/major page should have: (1) conceptual intro, (2) mental model and diagrams (described textually), (3) worked examples with code, (4) interpretation of results, (5) pitfalls and gotchas, (6) further reading.
• Use consistent terminology: multilayer network, multiplex network, heterogeneous network, node-layer pair, supra-adjacency matrix, etc.
• Keep all existing code samples but surround them with richer narrative, explanatory paragraphs, and “what you should notice” commentary.
• Whenever you introduce an algorithm, also describe its complexity, typical scale where it works, and when NOT to use it.
• Where relevant, reference canonical papers (Kivelä, Boccaletti, De Domenico, Mucha, Grover & Leskovec, etc.) in a short “Further reading” subsection.

Now, for each existing major doc section, do the following expansions.

1. “Overview” / Landing page

• Add a strong, narrative introduction answering:
  • “What is py3plex actually for?”
  • “What can I do in the first hour, first day, and first week with it?”
  • “When should I use py3plex instead of just NetworkX?”
• Add a subsection “Typical workflows” that outlines at least 3 concrete flows:
  1. Exploratory multilayer network analysis on a medium-sized dataset (few thousand nodes).
  2. Feature extraction + embeddings for ML tasks (classification/link prediction).
  3. Large-scale multilayer analysis with performance constraints.
• Add a short “Design at a glance” diagram description:
  • Core: multi_layer_network wrapper over NetworkX.
  • Algorithms: statistics, community detection, multilayer centrality, random walks.
  • Visualization: multilayer plotting, hairball/diagonal layouts.
  • IO: multiple formats & Arrow/Parquet for scale.

2. 5-Minute Quickstart

• Keep it short and runnable, but add:
  • A one-paragraph scenario: e.g. “You have two layers: ‘friends’ and ‘colleagues’ and want to see if the same people are central in both.”
  • After each code block, add 2–3 sentences explaining what just happened and how to sanity-check it (e.g. inspecting basic_stats output, understanding why nodes per layer look like that).
  • A final subsection “What you learned” summarizing the key mental model: node-layer pairs, layers as contexts, and how py3plex extends NetworkX.

3. “10-Minute Tutorial: Getting Started with py3plex”

• Convert this into a mini-chapter:
  • Add an opening story-style paragraph: “Imagine you are given a dataset of users interacting on two social platforms over time…”
  • For each step (creating, loading, exploring, computing statistics, community detection, random walks, visualization):
    • Prepend a short “Goal” sentence (“Goal: understand who is central across layers”, etc.).
    • For each metric (density, activity, overlap, centrality), explain what a high vs low value means in practice and how a researcher should interpret it.
  • Add a final “End-to-end example” where you:
    • Load a small synthetic or example multilayer network.
    • Run: basic_stats → a few multilayer statistics → community detection → one visualization.
    • Explain, in prose, how you would narrate these results in a research paper (2–3 paragraphs).

4. “Installation and Setup” + “Common Issues and Troublesho...

• Fixes binding text for pdf docs #650

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.