Skip to content

Commit

Permalink
Re-organise docs a little to make navigation easier (#877)
Browse files Browse the repository at this point in the history 
* Split Reading and Writing onto own pages

This allows us to have the explanations
and API references on one page, and then
that allows us to have an Examples page
with only examples (no API docs).
We can then bump up the headers so all the
examples appear in the side-bar, to be
easier to find.

Also move the contents list on the homepage
to below the welcome text, and restrict the
contents list on the examples page to only
list the examples (not other pages).

Overall this aims to avoid having deeply-nested
headers (which then don't appear in the sidebar,
making them harder to find), but without
breaking up the docs over too many pages.

* Make local docs build easier

* Fix automatic links to src code

* Add a few more cross-refs to docstring on prominent lines
  • Loading branch information
@nickrobinson251
nickrobinson251 authored Aug 27, 2021
1 parent 953636a commit 79f856f
Show file tree
Hide file tree
Showing 6 changed files with 293 additions and 292 deletions.
1 change: 1 addition & 0 deletions docs/Project.toml
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
[deps]
CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
9 changes: 5 additions & 4 deletions docs/make.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,16 @@ using Documenter, CSV

makedocs(;
modules=[CSV],
format=Documenter.HTML(),
format=Documenter.HTML(prettyurls=false),
pages=[
"Home" => "index.md",
"Examples" => "examples.md"
"Reading" => "reading.md",
"Writing" => "writing.md",
"Examples" => "examples.md",
],
repo="https://github.com/JuliaData/CSV.jl/blob/{commit}{path}#L{line}",
repo="https://github.com/JuliaData/CSV.jl/blob/{commit}{path}#{line}",
sitename="CSV.jl",
authors="Jacob Quinn",
assets=String[],
)

deploydocs(;
Expand Down
79 changes: 33 additions & 46 deletions docs/src/examples.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,10 @@
```@contents
Depth = 3
```

## API Reference
```@docs
CSV.read
CSV.File
CSV.Chunks
CSV.Rows
```
# Examples

## Utilities
```@docs
CSV.detect
```@contents
Pages = ["examples.md"]
```

## Examples

### [Non-UTF-8 character encodings](@id stringencodings)
## [Non-UTF-8 character encodings](@id stringencodings)

```julia
# assume I have csv text data encoded in ISO-8859-1 encoding
Expand All @@ -35,7 +22,7 @@ file = CSV.File(open("iso8859_encoded_file.csv", enc"ISO-8859-1"))
file = CSV.File(open("iso8859_encoded_file.csv", enc"ISO-8859-1"); buffer_in_memory=true)
```

### [Concatenate multiple inputs at once](@id vectorinputs)
## [Concatenate multiple inputs at once](@id vectorinputs)

```julia
using CSV
Expand All @@ -59,7 +46,7 @@ data = [
f = CSV.File(map(IOBuffer, data))
```

### [Gzipped input](@id gzipped_input)
## [Gzipped input](@id gzipped_input)

```julia
# assume I have csv text data compressed via gzip
Expand All @@ -76,7 +63,7 @@ file = CSV.File("data.gz")
file = CSV.File("data.gz"; buffer_in_memory=true)
```

### [Delimited data in a string](@id csv_string)
## [Delimited data in a string](@id csv_string)

```julia
using CSV
Expand All @@ -93,7 +80,7 @@ a,b,c
file = CSV.File(IOBuffer(data))
```

### [Data from the web/a url](@id http)
## [Data from the web/a url](@id http)

```julia
# assume there's delimited data I want to read from the web
Expand All @@ -116,7 +103,7 @@ http_response = Downloads.download(url)
file = CSV.File(http_response)
```

#### [Reading from a zip file](@id zip_example)
## [Reading from a zip file](@id zip_example)

```julia
using ZipFile, CSV, DataFrames
Expand Down Expand Up @@ -147,7 +134,7 @@ a == a_copy
close(z)
```

### [Column names on 2nd row](@id second_row_header)
## [Column names on 2nd row](@id second_row_header)

```julia
using CSV
Expand All @@ -166,7 +153,7 @@ a,b,c
file = CSV.File(IOBuffer(data); header=2)
```

### [No column names in data](@id no_header)
## [No column names in data](@id no_header)

```julia
using CSV
Expand All @@ -183,7 +170,7 @@ data = """
file = CSV.File(IOBuffer(data); header=false)
```

### [Manually provide column names](@id manual_header)
## [Manually provide column names](@id manual_header)

```julia
using CSV
Expand All @@ -203,7 +190,7 @@ file = CSV.File(IOBuffer(data); header=["a", "b", "c"])
file = CSV.File(IOBuffer(data); header=[:a, :b, :c])
```

### [Multi-row column names](@id multi_row_header)
## [Multi-row column names](@id multi_row_header)

```julia
using CSV
Expand All @@ -222,7 +209,7 @@ a,b,c
file = CSV.File(IOBuffer(data); header=[1, 2])
```

### [Normalizing column names](@id normalize_header)
## [Normalizing column names](@id normalize_header)

```julia
using CSV
Expand Down Expand Up @@ -256,7 +243,7 @@ column one,column two, column three
file = CSV.File(IOBuffer(data); normalizenames=true)
```

### [Skip to specific row where data starts](@id skipto_example)
## [Skip to specific row where data starts](@id skipto_example)

```julia
using CSV
Expand All @@ -276,7 +263,7 @@ descriptive row that gives information about the data that we'd like to ignore
file = CSV.File(IOBuffer(data); header=false, skipto=2)
```

### [Skipping trailing useless rows](@id footerskip_example)
## [Skipping trailing useless rows](@id footerskip_example)

```julia
using CSV
Expand All @@ -299,7 +286,7 @@ grand total: 45
file = CSV.File(IOBuffer(data); footerskip=2)
```

### [Reading transposed data](@id transpose_example)
## [Reading transposed data](@id transpose_example)

```julia
using CSV
Expand All @@ -318,7 +305,7 @@ c,3,6,9
file = CSV.File(IOBuffer(data); transpose=true)
```

### [Ignoring commented rows](@id comment_example)
## [Ignoring commented rows](@id comment_example)

```julia
using CSV
Expand All @@ -337,7 +324,7 @@ a,b,c
file = CSV.File(IOBuffer(data); comment="#")
```

### [Ignoring empty rows](@id ignoreemptyrows_example)
## [Ignoring empty rows](@id ignoreemptyrows_example)

```julia
using CSV
Expand All @@ -359,7 +346,7 @@ a,b,c
file = CSV.File(IOBuffer(data); ignoreemptyrows=true)
```

### [Including/excluding columns](@id select_example)
## [Including/excluding columns](@id select_example)

```julia
using CSV
Expand Down Expand Up @@ -390,7 +377,7 @@ file = CSV.File(file; drop=[false, true, false])
file = CSV.File(file; drop=(i, nm) -> i == 2)
```

### [Limiting number of rows from data](@id limit_example)
## [Limiting number of rows from data](@id limit_example)

```julia
using CSV
Expand All @@ -413,7 +400,7 @@ a,b,c
file = CSV.File(IOBuffer(data); limit=3)
```

### [Specifying custom missing strings](@id missing_string_example)
## [Specifying custom missing strings](@id missing_string_example)

```julia
using CSV
Expand All @@ -434,7 +421,7 @@ code,age,score
file = CSV.File(file; missingstring=["-999", "NA"])
```

### [String delimiter](@id string_delim)
## [String delimiter](@id string_delim)

```julia
using CSV
Expand All @@ -451,7 +438,7 @@ col1::col2
file = CSV.File(file; delim="::")
```

### [Fixed width files](@id ignorerepeated_example)
## [Fixed width files](@id ignorerepeated_example)

```julia
using CSV
Expand All @@ -473,7 +460,7 @@ col1 col2 col3
file = CSV.File(file; delim=' ', ignorerepeated=true)
```

### [Turning off quoted cell parsing](@id quoted_example)
## [Turning off quoted cell parsing](@id quoted_example)

```julia
using CSV
Expand All @@ -496,7 +483,7 @@ sailor,6,7
file = CSV.File(IOBuffer(data); quoted=false)
```

### [Quoted & escaped fields](@id quotechar_example)
## [Quoted & escaped fields](@id quotechar_example)

```julia
using CSV
Expand All @@ -520,7 +507,7 @@ file = CSV.File(file; openquotechar='"' closequotechar='"', escapechar='"')
```


### [DateFormat](@id dateformat_example)
## [DateFormat](@id dateformat_example)

```julia
using CSV
Expand All @@ -538,7 +525,7 @@ code,date
file = CSV.File(file; dateformat="yyyy/mm/dd")
```

### [Custom decimal separator](@id decimal_example)
## [Custom decimal separator](@id decimal_example)

```julia
using CSV
Expand All @@ -555,7 +542,7 @@ col1;col2;col3
file = CSV.File(file; delim=';', decimal=',')
```

### [Custom bool strings](@id truestrings_example)
## [Custom bool strings](@id truestrings_example)

```julia
using CSV
Expand All @@ -573,7 +560,7 @@ id,paid,attended
file = CSV.File(file; truestrings=["T", "TRUE"], falsestrings=["F", "FALSE"])
```

### [Matrix-like Data](@id matrix_example)
## [Matrix-like Data](@id matrix_example)

```julia
using CSV
Expand All @@ -591,7 +578,7 @@ file = CSV.File(file; header=false)
file = CSV.File(file; header=false, delim=' ', types=Float64)
```

### [Providing types](@id types_example)
## [Providing types](@id types_example)

```julia
using CSV
Expand All @@ -618,7 +605,7 @@ file = CSV.File(file; types=[Int, Int, Int], silencewarnings=true)
file = CSV.File(file; types=[Int, Int, Int], strict=true)
```

### [Typemap](@id typemap_example)
## [Typemap](@id typemap_example)

```julia
using CSV
Expand All @@ -637,7 +624,7 @@ file = CSV.File(file; typemap=Dict(Int => String))
file = CSV.File(file; types=Dict(:zipcode => String))
```

### [Pooled values](@id pool_example)
## [Pooled values](@id pool_example)

```julia
using CSV
Expand Down
Loading

0 comments on commit 79f856f

Please sign in to comment.