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 improvements (meta) #2385

Closed
6 of 10 tasks
abey79 opened this issue Jun 12, 2023 · 2 comments
Closed
6 of 10 tasks

Documentation improvements (meta) #2385

abey79 opened this issue Jun 12, 2023 · 2 comments
Labels
🧑‍💻 dev experience developer experience (excluding CI) 📖 documentation Improvements or additions to documentation

Comments

@abey79
Copy link
Member

abey79 commented Jun 12, 2023 •
edited
Loading

Quick and dirty issue to list "early user" documentation issues from my experience.

Coverage holes:

For 0.8 only??

  • Blueprint stuff entirely missing from the concepts section
  • Blueprint stuff entirely missing from the Python common API page (although an "Experimental" section already exists)

Long term/subjective/TBD:

  • All API mentioned in docs should link into refs
  • Wording around annotation/class stuff "sounds" way more generic that it actually is (see Improving on Annotation Context (meta) #2405)
  • Use "book" style to introduce concepts
    • each chapter builds on previous chapter, rather than introducing concepts in isolation and seemingly random order
    • each chapter contains more code examples
    • Next/prev buttons, etc. to encourage a more systematic reading (as opposed to the current "trust your instincts, read specific topic when needed" approach.
@abey79 abey79 added 📖 documentation Improvements or additions to documentation 🧑‍💻 dev experience developer experience (excluding CI) labels Jun 12, 2023
@abey79 abey79 changed the title Document improvements (meta) Documentation improvements (meta) Jun 12, 2023
@jleibs jleibs mentioned this issue Jun 13, 2023
Merged
3 tasks
jleibs added a commit that referenced this issue Jun 13, 2023
@jleibs
Add support for classes to generated python common API index (#2401)
d8d6445 
### What

Classes such as `ClassDescription` and `AnnotationInfo` make up an
import part of the API surface for many rerun APIs. Add support for the
classes to `gen_common_index.py`.

TODO:
 - [ ] After landing, cherry-pick into release-0.6

Additional:
- set the heading_level for these generated components to 4, which
matches the styling from the full package index and results in better
TOC representation.
- Add the same template modification that we use from functions to
disable `first` so we get a continuity bar for the class rendering like
we do for functions.
 - Modify the CSS so that links are visible.

Previews:

![image](https://github.com/rerun-io/rerun/assets/3312232/ec0bd281-da4e-4a9a-886b-1689a41ea0ca)



![image](https://github.com/rerun-io/rerun/assets/3312232/3e48e72a-abef-408c-8731-18fead234679)

Related to: #2385
Closes: #2393


### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [ ] I've included a screenshot or gif (if applicable)

<!-- This line will get updated when the PR build summary job finishes.
-->
PR Build Summary: https://build.rerun.io/pr/2401

<!-- pr-link-docs:start -->
Docs preview: https://rerun.io/preview/b58a10c/docs
Examples preview: https://rerun.io/preview/b58a10c/examples
<!-- pr-link-docs:end -->
jleibs added a commit that referenced this issue Jun 13, 2023
@jleibs
Add support for classes to generated python common API index (#2401)
77ccc0e 
Classes such as `ClassDescription` and `AnnotationInfo` make up an
import part of the API surface for many rerun APIs. Add support for the
classes to `gen_common_index.py`.

TODO:
 - [ ] After landing, cherry-pick into release-0.6

Additional:
- set the heading_level for these generated components to 4, which
matches the styling from the full package index and results in better
TOC representation.
- Add the same template modification that we use from functions to
disable `first` so we get a continuity bar for the class rendering like
we do for functions.
 - Modify the CSS so that links are visible.

Previews:

![image](https://github.com/rerun-io/rerun/assets/3312232/ec0bd281-da4e-4a9a-886b-1689a41ea0ca)

![image](https://github.com/rerun-io/rerun/assets/3312232/3e48e72a-abef-408c-8731-18fead234679)

Related to: #2385
Closes: #2393

* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [ ] I've included a screenshot or gif (if applicable)

<!-- This line will get updated when the PR build summary job finishes.
-->
PR Build Summary: https://build.rerun.io/pr/2401

<!-- pr-link-docs:start -->
Docs preview: https://rerun.io/preview/b58a10c/docs
Examples preview: https://rerun.io/preview/b58a10c/examples
<!-- pr-link-docs:end -->
emilk pushed a commit that referenced this issue Jun 15, 2023
@jleibs @emilk
Add support for classes to generated python common API index (#2401)
dd22283 
Classes such as `ClassDescription` and `AnnotationInfo` make up an
import part of the API surface for many rerun APIs. Add support for the
classes to `gen_common_index.py`.

TODO:
 - [ ] After landing, cherry-pick into release-0.6

Additional:
- set the heading_level for these generated components to 4, which
matches the styling from the full package index and results in better
TOC representation.
- Add the same template modification that we use from functions to
disable `first` so we get a continuity bar for the class rendering like
we do for functions.
 - Modify the CSS so that links are visible.

Previews:

![image](https://github.com/rerun-io/rerun/assets/3312232/ec0bd281-da4e-4a9a-886b-1689a41ea0ca)

![image](https://github.com/rerun-io/rerun/assets/3312232/3e48e72a-abef-408c-8731-18fead234679)

Related to: #2385
Closes: #2393

* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [ ] I've included a screenshot or gif (if applicable)

<!-- This line will get updated when the PR build summary job finishes.
-->
PR Build Summary: https://build.rerun.io/pr/2401

<!-- pr-link-docs:start -->
Docs preview: https://rerun.io/preview/b58a10c/docs
Examples preview: https://rerun.io/preview/b58a10c/examples
<!-- pr-link-docs:end -->
@emilk
Copy link
Member

emilk commented Aug 8, 2023

Let's clean up what's left to do here

@abey79
Copy link
Member Author

abey79 commented Aug 18, 2023

I think we can close this as everything is either:

  • done
  • properly logged as issues scheduled for planning consideration
  • obvious/very long-term/likely to be revisited anyway stuff

@abey79 abey79 closed this as completed Aug 18, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
🧑‍💻 dev experience developer experience (excluding CI) 📖 documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@emilk @abey79