drivendataorg/cloudpathlib
Documentation updates content + style
Aberta
#133 aberto em 13 de mar. de 2021
documentationgood first issue
Métricas do repositório
- Stars
- (624 estrelas)
- Métricas de merge de PR
- (Métricas PR pendentes)
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
- 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
cachingpage -
Example usage on thelink AnyPath usage page from the AnyPath API reference page.AnyPathpage
Style:
- The layout of method signatures 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/Outblocks from the notebooks that we use in the docs like we do on the DrivenData blog.