drivendataorg / drivendataorg/cloudpathlib

Documentation updates content + style

Open
#133 1 comment 0 reactions 0 assignees View on GitHub
documentation good first issue
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.