Add Quickstart Section to Improve Beginner Onboarding in libpysal Documentation

[AKSrivastava28]

Hi all,

While going through the libpysal documentation, I was exploring how a new user might get started with the package. Although the documentation is comprehensive and well-structured, I found that it is largely API-driven, and it may not immediately highlight a minimal end-to-end example for first-time users.

I would like to propose adding a small “Quickstart” section near the top of the documentation that could include:

• A short conceptual overview of what libpysal provides
• A minimal working example (e.g., loading a dataset and constructing spatial weights)
• A brief note on how libpysal connects to other PySAL subpackages

The goal would be to provide a clear entry point for new users before they move into the detailed API reference.

If this seems like a useful addition, I would be happy to draft a PR implementing it. I would also appreciate any guidance on where such a section would best fit within the current documentation structure.

Best,
Ananya

[martinfleis]

Hi, yes. We are aware that some parts of the documentation would need some love and this is one of them.

Though, I am curious why you think that after figuring out how to start with the package yourself, you think you can guide others in that.

[AKSrivastava28]

Hi, thanks for the response.

That’s a fair question. While exploring the libpysal documentation, I tried to understand how a new user might get started with the package by following the existing documentation structure.

During this process, I noticed that the documentation quickly moves into module descriptions and API references, and it was not immediately obvious what a minimal working workflow might look like (for example: loading a dataset, constructing spatial weights, and inspecting the result).

While exploring the docs, I found myself navigating between different sections to piece together that basic workflow. That experience made me think a small Quickstart example could help provide a clearer entry point for new users.

My intention is not to redesign the documentation structure, but rather to contribute a concise example demonstrating a minimal libpysal workflow and helping users understand where the package fits within the broader PySAL ecosystem.

If that direction seems reasonable, I’d be happy to draft a concrete example and open a PR for discussion.

[AKSrivastava28]

Hi @martinfleis, just following up on this discussion.

I’ve started drafting a minimal quickstart example locally to illustrate a basic libpysal workflow (loading a dataset and constructing spatial weights).

If this direction looks reasonable, I can prepare a PR for review. Please let me know if you would prefer the example to be placed in a specific section of the documentation (e.g., user guide or a new quickstart page).

Thanks!

[martinfleis]

The current documentation structure is not well suited for this. We need to do some higher level infrastructural work first.

[AKSrivastava28]

Thanks for the clarification.

That makes sense. If the current documentation structure isn’t well suited for adding something like a quickstart yet, I’d be interested in understanding what kind of higher-level infrastructure changes are needed first.

Are there particular areas of the documentation system (for example structure, tooling, navigation, or cross-package organization) that contributors could start exploring or helping with?

I’d be happy to look into those aspects and contribute there instead.

[martinfleis]

The core PySAL team will meet next week to discuss how to approach this (among other things). Patience please :).