(Go: >> BACK << -|- >> HOME <<)
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.

Sign up for GitHub

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

Jump to bottom

Documentation content #10

Merged
merged 2 commits into from
Jan 15, 2021
Merged

Documentation content #10

merged 2 commits into from
Jan 15, 2021

Conversation

felix-hilden
Copy link
Contributor
@felix-hilden felix-hilden commented Jan 14, 2021 •
edited
Loading

From #8: Here's some initial documentation content and structure. I think this PR should eventually actually break down the GitHub readme into different sections in the documentation, but as it stands, the file has 2k+ lines, and I'm most likely not the one to decide where each section goes and should they stay the same.

As I already stated in the linked issue, the documentation could be divided into two sections. One for the package, and another for guides and other explanations. So maybe this would be the way to go:

  • index: introductory funzies and a tl;dr, links to other places, maybe a short description of features
  • package:
    • changes: a version changelog
    • reference: API description and reference documentation
    • development: roadmap, news etc. if you'd like to have that on RTD instead of GitHub
  • guide:
    • tutorial: cheat sheet, quickstart, whatever
    • explanations: inside look, mathematical descriptions, that sorta stuff

What do you think?

@leycec leycec mentioned this pull request Jan 15, 2021
Merged
@leycec
Copy link
Member
leycec commented Jan 15, 2021 •
edited
Loading

This... looks perfect! Sufficiently perfect, in fact, that I'm already merging this. I love these smaller incremental PRs that get merged rapidly rather than giant monolithic PRs that never, ever get merged. Ambition is admirable, but let's be ambitious over time rather than all at once.

This also lets me immediately begin importing this repository into RTD and getting a feel for the build workflow and rendering output, which is invaluable.

Thanks again for your tremendous contributions, Felix! I'm adding a new Contributors section to our documentation expressing my eternal gratitude. This is me gratefully bowing to you. 🙇

I'll continue hacking our README.rst into this bold, new structure. Meanwhile, keep those spicy PRs comin' for however long you can keep that enthusiasm afloat. I promise not to squander your zeal for human-readability.

@leycec
Copy link
Member
leycec commented Jan 15, 2021 •
edited
Loading

Oh, and thanks for catching my beartype.__init__ docstring failures. I foolishly didn't realize that Sphinx only picked up variable assignments rather than merely references.

It makes sense. The more you know. 🤔

@leycec leycec merged commit 238d2fa into beartype:master Jan 15, 2021
@felix-hilden
Copy link
Contributor Author

Perfect, thanks a bunch!

@felix-hilden felix-hilden deleted the doc-content branch January 21, 2021 09:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
2 participants
@felix-hilden @leycec