drivendataorg / drivendataorg/cloudpathlib
Documentation updates content + style
- Dominant language
- Python
- Stars
- 628
- Forks
- 88
- Avg merge
- 17h 28m
- Merged PRs (30d)
- 2
Description
I had a few thoughts while looking at #132 that may be useful for improving our documentation content and styling
Content:
- [ ] "Getting started" page - usually the first page I click on, which should be mostly code and have steps for install, instatiation and simple read/write examples.
- [ ] Examples/cookbook/common use cases (download files, listing dir, globbing, persistent cache)
- [ ] Note about file handles [like in this comment](https://github.com/drivendataorg/cloudpathlib/issues/481#issuecomment-2447437700)
- [ ] Maybe the authentication/caching pages go under an "Advanced" header in the TOC?
- [ ] URI schemes should feature prominently on the homepage/getting started page/methods table, etc. (you have to dig in to find these at the moment)
- [ ] Would be helpful to have some diagrams, especially on the `caching` page
- [ ] ~~Example usage on the `AnyPath` page~~ link [AnyPath usage page](https://cloudpathlib.drivendata.org/anypath-polymorphism/) from the [AnyPath API reference page](https://cloudpathlib.drivendata.org/api-reference/anypath/).
Style:
- The [layout of method signatures](https://cloudpathlib.drivendata.org/api-reference/s3client/#cloudpathlib.s3.s3client.S3Client-methods) can be hard to read. A couple of potential ideas to improve are: (1) remove type hints when laying these out since duplicated below, (2) automatically style these to put each param on a new line, (3) decrease font size, (4)
- Can we strip the `In`/`Out` blocks from the [notebooks that we use in the docs](https://cloudpathlib.drivendata.org/why_cloudpathlib/) like we do [on the DrivenData blog](https://www.drivendata.co/blog/model-geomagnetic-field-benchmark/).
Contributor guide
Assessment
This issue has not been assessed yet.