added docs and updated list of tables

tbeason · Aug 6, 2020 · cbf3c35 · cbf3c35 · tbeason · Aug 6, 2020
1 parent 080aa9e
commit cbf3c35
Show file tree

Hide file tree

Showing 9 changed files with 109 additions and 43 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,5 +4,4 @@
 /deps/deps.jl
 /docs/build
 Manifest.toml
-/docs
 /.vscode
diff --git a/.travis.yml b/.travis.yml
@@ -16,14 +16,14 @@ git:
 
 jobs:
  ## uncomment following lines to deploy documentation
- # include:
- #  - stage: "Documentation"
- #  julia: 1.3
- #  os: linux
- #  script:
- #  - julia --project=docs -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=pwd()))'
- #  - julia --project=docs --color=yes docs/make.jl
- #  after_success: skip
+ include:
+ - stage: "Documentation"
+ julia: 1.5
+ os: linux
+ script:
+ - julia --project=docs -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate();'
+ - julia --project=docs --color=yes docs/make.jl
+ after_success: skip
  allow_failures:
  - julia: nightly
 after_success:

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "FamaFrenchData"
 uuid = "bd2a388e-9788-4ef7-9fc3-f4c919ffde82"
 authors = ["Tyler Beason <tbeas12@gmail.com>"]
-version = "0.1.4"
+version = "0.1.5"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

diff --git a/README.md b/README.md
@@ -1,17 +1,16 @@
 # FamaFrenchData.jl
 
-![Lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)<!--
-![Lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)
-![Lifecycle](https://img.shields.io/badge/lifecycle-stable-green.svg)
-![Lifecycle](https://img.shields.io/badge/lifecycle-retired-orange.svg)
-![Lifecycle](https://img.shields.io/badge/lifecycle-archived-red.svg)
-![Lifecycle](https://img.shields.io/badge/lifecycle-dormant-blue.svg) -->
+[![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://tbeason.github.io/FamaFrenchData.jl/stable)
+<!--[![Documentation](https://img.shields.io/badge/docs-master-blue.svg)](https://tbeason.github.io/FamaFrenchData.jl/dev)-->
+![Lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)
+<!-- ![Lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg) -->
+<!-- ![Lifecycle](https://img.shields.io/badge/lifecycle-stable-green.svg) -->
+<!-- ![Lifecycle](https://img.shields.io/badge/lifecycle-retired-orange.svg) -->
+<!-- ![Lifecycle](https://img.shields.io/badge/lifecycle-archived-red.svg) -->
+<!-- ![Lifecycle](https://img.shields.io/badge/lifecycle-dormant-blue.svg) -->
 [![Build Status](https://travis-ci.com/tbeason/FamaFrenchData.jl.svg?branch=master)](https://travis-ci.com/tbeason/FamaFrenchData.jl)
 [![codecov.io](http://codecov.io/github/tbeason/FamaFrenchData.jl/coverage.svg?branch=master)](http://codecov.io/github/tbeason/FamaFrenchData.jl?branch=master)
-<!--
-[![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://tbeason.github.io/FamaFrenchData.jl/stable)
-[![Documentation](https://img.shields.io/badge/docs-master-blue.svg)](https://tbeason.github.io/FamaFrenchData.jl/dev)
--->
+
 
 A Julia package for easy access to the [Ken French Data Library](https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html). The Ken French Data Library is one of the most highly used publicly available data sources for financial investments and asset pricing research.
 
@@ -28,6 +27,8 @@ The package exports 3 functions: `readFamaFrench`, `downloadFamaFrench`, and `li
 
 For help with any of these functions, use `?` at the REPL (eg. `?readFamaFrench`).
 
+Please consult the online [documentation](https://tbeason.github.io/FamaFrenchData.jl/stable) for additional detail.
+
 ## Example 
 The Fama-French 3 factor model is a commonly used empirical asset pricing model. This example retrieves the full time series of FF3 monthly and annual returns.
 
@@ -40,27 +41,6 @@ FF3_monthly = tables[1]
 FF3_annual = tables[2]
 ```
 
-If you would rather store the file locally (perhaps so your code is reproducible later on), use `downloadFamaFrench`.
-
-```julia
-savename = "path/to/my/file.csv"
-downloadFamaFrench(savename,"F-F_Research_Data_Factors")
-tables, tablenotes, filenotes = readFamaFrench(savename) # also reads local files
-```
-
-To get a list of all of the available table names, use `listFamaFrench`.
-
-```julia
-FFnames = listFamaFrench()
-```
-
-## Additional Notes
-
- - Original files use `-99.99` or `-999` to encode missing values, I attempt to replace these with `missing`.
- - Original files have no column heading for column 1, I name this column `:Date`. It maintains the parsed type of `Int` because it can take several different forms: `20011231`,`200112`,`2001`.
- - I have not verified that all tables are parsed correctly.
- - Breakpoints files require the keyword argument `header=false`
-
 
 ## Disclaimer
 

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,5 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.25"
diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,15 @@
+using Documenter, FamaFrenchData
+
+
+makedocs(
+ sitename = "FamaFrenchData.jl",
+ modules=[FamaFrenchData],
+ pages=["Home"=>"index.md"],
+ format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true")
+)
+
+
+deploydocs(
+ repo = "github.com/tbeason/FamaFrenchData.jl.git",
+ push_preview=true
+)
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,65 @@
+# FamaFrenchData.jl
+
+[FamaFrenchData.jl](https://github.com/tbeason/FamaFrenchData.jl) is a Julia package providing access to the Fama-French data available on the [Ken French Data Library](https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html). Working with the data is sometimes tedious because the downloadable files come (1) compressed in `zip` archives and (2) having non-standard `csv` layouts. This package handles both of those hurdles, allowing users to get to the data faster.
+
+## Usage
+
+To add the package, type `] add FamaFrenchData` at the Julia REPL.
+
+Once added, type `using FamaFrenchData` to import the package.
+
+The package exports 3 functions: `readFamaFrench`, `downloadFamaFrench`, and `listFamaFrench`.
+
+For help with any of these functions, use `?` at the REPL (eg. `?readFamaFrench`).
+
+## Example 
+The Fama-French 3 factor model is a commonly used empirical asset pricing model. This example retrieves the full time series of FF3 monthly and annual returns.
+
+```julia
+using FamaFrenchData, DataFrames
+
+tables, tablenotes, filenotes = readFamaFrench("F-F_Research_Data_Factors")
+
+FF3_monthly = tables[1]
+FF3_annual = tables[2]
+```
+
+If you would rather store the file locally (perhaps so your code is reproducible later on), use `downloadFamaFrench`.
+
+```julia
+using FamaFrenchData, DataFrames
+
+savename = "path/to/my/file.csv"
+downloadFamaFrench(savename,"F-F_Research_Data_Factors")
+tables, tablenotes, filenotes = readFamaFrench(savename) # also reads local files
+```
+
+To get a list of all of the available table names, use `listFamaFrench`.
+
+```julia
+using FamaFrenchData
+FFnames = listFamaFrench()
+```
+
+## Additional Notes
+
+ - Original files use `-99.99` or `-999` to encode missing values, I attempt to replace these with `missing`.
+ - Original files have no column heading for column 1, I name this column `:Date`. It maintains the parsed type of `Int` because it can take several different forms: `20011231`,`200112`,`2001`.
+ - I have not verified that all tables are parsed correctly.
+ - Breakpoints files require the keyword argument `header=false`
+
+
+## Disclaimer
+
+
+I am not affiliated with the Ken French Data Library. This package does not "ship with" the data, just provides easier access to it. Other than the changes that I have explicitly stated, I do not alter the data; however, it is your responsibility to verify that the data is correct.
+
+
+## API
+
+
+```@docs
+readFamaFrench
+downloadFamaFrench
+listFamaFrench
+```
diff --git a/listFamaFrench.txt b/listFamaFrench.txt
@@ -1,4 +1,4 @@
-# Generated by FamaFrenchData.jl 2020-03-14T22:10:45.712
+# Generated by FamaFrenchData.jl 2020-08-06T09:51:34.688
 F-F_Research_Data_Factors
 F-F_Research_Data_Factors_weekly
 F-F_Research_Data_Factors_daily
@@ -12,8 +12,10 @@ Portfolios_Formed_on_BE-ME_Wout_Div
 Portfolios_Formed_on_BE-ME_Daily
 Portfolios_Formed_on_OP
 Portfolios_Formed_on_OP_Wout_Div
+Portfolios_Formed_on_OP_Daily
 Portfolios_Formed_on_INV
 Portfolios_Formed_on_INV_Wout_Div
+Portfolios_Formed_on_INV_Daily
 6_Portfolios_2x3
 6_Portfolios_2x3_Wout_Div
 6_Portfolios_2x3_weekly

diff --git a/src/FamaFrenchData.jl b/src/FamaFrenchData.jl
@@ -19,7 +19,7 @@ const KFDLftp = "http://mba.tuck.dartmouth.edu/pages/faculty/ken.french/ftp/"
  readFamaFrench(ffn;kwargs...)
 
 `ffn` can be the table name (in which case it is retreived from the web) or a path to the local file.
-`kwargs` are passed to `CSV.read`. Missing values (`-99.99` or `-999`) are replaced with `missing`.
+`kwargs` are passed to `CSV.File`. Missing values (`-99.99` or `-999`) are replaced with `missing`.
 
 Returns three pieces: