Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Example Gallery #714

Open
mmcky opened this issue Jul 12, 2023 · 3 comments
Open

ENH: Example Gallery #714

mmcky opened this issue Jul 12, 2023 · 3 comments

Comments

@mmcky
Copy link
Contributor

mmcky commented Jul 12, 2023

The old example gallery is outdated and should be archived.

The QuantEcon Lectures provides lots of examples, and we do have examples in the documentation (i.e. docstrings), perhaps we can construct a demo gallery using those examples to be more directly accessible?

@jstac
Copy link
Contributor

jstac commented Jul 12, 2023

+1

@janosg
Copy link

janosg commented Jul 12, 2023

If you are thinking about a general re-organization of the documentation, I would like to suggest this system which I found very helpful in my own projects. It groups documentation in four categories:

  • Reference: This is helpful for experienced users who want to look up a specific syntax. The current documentation is almost exclusively written in reference style (auto-generated from docstrings)
  • Explanation: This is helpful for people who want to learn the economics/numerics and syntax at the same time. This is the style of the quantecon lectures.
  • Tutorials: Tutorials help newbies to discover the functionality of a package. In my experience, tutorials can increase the adoption of a package. The submitted paper is written in tutorial style, Having a notebook with all examples from the paper would be a great getting started tutorial.
  • How-To Guides: How-To Guides show how to achieve a very specific task without explaining any background that is not immediately relevant. I think this is not covered in the current documentation.

A great example of documentation that uses this system is pytask

@mmcky
Copy link
Contributor Author

mmcky commented Jul 13, 2023

thanks @janosg -- nice suggestion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants