Merge pull request #27 from shizejin/add_docs

WIP: Add docs using Documenter.jl

Author: oyamad

.gitignore

@@ -1,3 +1,5 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+docs/build/
+docs/site/

.travis.yml

@@ -4,7 +4,7 @@ os:
   - linux
   - osx
 julia:
-  - release
+  - 0.5
   - nightly
 matrix:
   allow_failures:
@@ -18,3 +18,6 @@ notifications:
 #script:
 #  - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
 #  - julia -e 'Pkg.clone(pwd()); Pkg.build("Games"); Pkg.test("Games"; coverage=true)'
+after_success:
+  - julia -e 'Pkg.add("Documenter")'
+  - julia -e 'cd(Pkg.dir("Games")); include(joinpath("docs", "make.jl"))'

docs/README.md

@@ -0,0 +1,20 @@
+## Generate docs automatically
+
+Run
+```
+$julia make.jl
+```
+
+The generated docs can be accessed in `build/index.html`.
+
+You may modify `Structure` to arrange the structure of the website to be generated. For example:
+
+```
+Order: normal_form_game, Computing Nash equilibria, Repeated Game
+Computing Nash equilibria: pure_nash, support_enumeration
+Repeated Game: repeated_game_util, repeated_game
+```
+
+The first line sets the order of pages. You can add a file name if you want it to generate a single page, or the name of section you want to create. In the following you need to declare which files are included in each section. Note that you shouldn't put a comma or dot at the end of each line.
+
+It is not necessary to declare structure for every file included in the Module. Files not mentioned in `Structure` will simply generate a single page automatically.

docs/Structure

@@ -0,0 +1,3 @@
+Order: normal_form_game, Computing Nash Equilibria, Repeated Game
+Computing Nash Equilibria: pure_nash
+Repeated Game: repeated_game_util, repeated_game

docs/auto_doc_gen.jl

@@ -0,0 +1,180 @@
+#=
+Generate markdown files automatically, for generating
+docs using `Documenter.jl`.
+
+@author: Zejin Shi
+
+=#
+
+path = Pkg.dir("Games")
+
+# read the basic structures
+order = SubString{String}[]
+sections_names = SubString{String}[]
+sections = Dict{SubString{String}, Vector{SubString{String}}}()
+re = r"(.*): (.*)\n"
+open(joinpath(path, "docs/Structure")) do f
+    for match in eachmatch(re, readstring(f))
+        list = map(i -> strip(i), split(match.captures[2], ","))
+        if list ==[""]
+            continue
+        end
+
+        if match.captures[1] == "Order"
+            order = list
+            global order
+        else
+            section_name = match.captures[1]
+            push!(sections_names, section_name)
+            sections[section_name] = list
+        end
+    end
+end
+
+# find all files used in Games.jl
+re = r"include\(\"(.*)\.jl\"\)"
+files = String[]
+
+open(joinpath(path, "src/Games.jl")) do f
+    for match in eachmatch(re, readstring(f))
+        push!(files, match.captures[1])
+    end
+end
+
+files_names = Dict{String, String}(
+                file => replace(join(map(ucfirst, split(file, "_")), " "),
+                                "Util",
+                                "Utilities")
+                for file in files
+                )
+
+# generate paths
+if !ispath(joinpath(path, "docs/src/lib"))
+    mkpath(joinpath(path, "docs/src/lib"))
+end
+
+# write .md for files not in section
+for file in files
+    if file in vcat(values(sections)...)
+        continue
+    end
+
+    if !(file in order)
+        push!(order, file)
+    end
+    file_name = files_names[file]
+    file_page = """
+# [$file_name](@id $file)
+
+This is documentation for `$file.jl`.
+
+## Exported
+
+```@autodocs
+Modules = [Games]
+Pages   = ["$file.jl"]
+Private = false
+```
+
+## Internal
+
+```@autodocs
+Modules = [Games]
+Pages   = ["$file.jl"]
+Public = false
+```
+"""
+    open(joinpath(path, "docs/src/lib/$file.md"), "w") do f
+        write(f, file_page)
+    end
+end
+
+# write .md for sections
+for section_name in sections_names
+    if !(section_name in order)
+        push!(order, section_name)
+    end
+
+    section_files = sections[section_name]
+    section_name_lower = replace(lowercase(section_name), " ", "_")
+    section_page = """
+# $section_name
+
+This is documentation for $section_name.
+"""
+    open(joinpath(path, "docs/src/lib/$section_name_lower.md"), "w") do f
+        write(f, section_page)
+        for file in section_files
+            file_name = files_names[file]
+            section_file_page = """
+
+## [$file_name](@id $file)
+
+Documentation for `$file.jl`.
+
+### Exported
+```@autodocs
+Modules = [Games]
+Pages   = ["$file.jl"]
+Private = false
+```
+
+### Internal
+```@autodocs
+Modules = [Games]
+Pages   = ["$file.jl"]
+Public = false
+```
+"""
+            write(f, section_file_page)
+        end
+    end
+end
+
+# write index page for Liabrary
+index = """
+# Index
+
+```@index
+modules = [Games]
+```
+"""
+
+open(joinpath(path, "docs/src/lib/index.md"), "w") do f
+    write(f, index)
+end
+
+# write index.md as Homepage
+home_page = """
+# Games.jl
+
+"""
+
+open(joinpath(path, "docs/src/index.md"), "w") do f
+    write(f, home_page)
+    for page in order
+        if page in keys(sections)
+            write(f, "$page\n")
+            for file in sections[page]
+                file_name = files_names[file]
+                write(f, "* [$file_name](@ref $file)\n")
+            end
+            write(f, "\n")
+        else
+            file = page
+            file_name = files_names[file]
+            write(f, "[$file_name](@ref $file)\n\n")
+        end
+    end
+end
+
+pages_names = map(i -> replace(lowercase(i), " ", "_"), order)
+
+PAGES = ["Home" => "index.md",
+         "Library" => push!(
+                        ["lib/$page_name.md" 
+                         for page_name in pages_names
+                        ],
+                         "lib/index.md"
+                    )
+    ]

docs/make.jl

@@ -0,0 +1,20 @@
+using Documenter, Games
+
+include("auto_doc_gen.jl")
+
+makedocs(
+    modules = [Games],
+    format = :html,
+    sitename = "Games.jl",
+    pages = PAGES,
+)
+
+deploydocs(
+    repo = "github.com/QuantEcon/Games.jl.git",
+    branch = "gh-pages",
+    target = "build",
+    osname = "linux",
+    julia  = "0.5",
+    deps = nothing,
+    make = nothing,
+)