Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3 from tpetricek/master
Adding documentation tools
- Loading branch information
Showing
14 changed files
with
844 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| @echo off | ||
| if not exist packages\FAKE\tools\Fake.exe ( | ||
| .nuget\nuget.exe install FAKE -OutputDirectory packages -ExcludeVersion -Prerelease | ||
| ) | ||
| packages\FAKE\tools\FAKE.exe build.fsx %* | ||
| pause |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,188 @@ | ||
| // -------------------------------------------------------------------------------------- | ||
| // FAKE build script | ||
| // -------------------------------------------------------------------------------------- | ||
|
|
||
| #r @"packages/FAKE/tools/FakeLib.dll" | ||
|
|
||
| open System | ||
| open System.IO | ||
| open System.Text.RegularExpressions | ||
| open Fake | ||
| open Fake.AssemblyInfoFile | ||
| open Fake.Git | ||
|
|
||
| Environment.CurrentDirectory <- __SOURCE_DIRECTORY__ | ||
|
|
||
| let files includes = | ||
| { BaseDirectories = [__SOURCE_DIRECTORY__] | ||
| Includes = includes | ||
| Excludes = [] } |> Scan | ||
|
|
||
| // Information about the project to be used at NuGet and in AssemblyInfo files | ||
| let project = "FSharp.DataFrame" | ||
| let authors = ["Blue Mountain Capital"] | ||
| let summary = "Easy to use F# library for data manipulation and scientific programming" | ||
| let description = """ | ||
| The F# DataFrame library (FSharp.DataFrame.dll) implements an efficient and robust | ||
| data frame and series structures for manipulating with structured data. It supports | ||
| handling of missing values, aggregations, grouping, joining, statistical functions and | ||
| more. For frames and series with ordered indices (such as time series), automatic | ||
| alignment is also available. """ | ||
|
|
||
| let tags = "F# fsharp data frame series statistics science" | ||
|
|
||
| // Read additional information from the release notes document | ||
| // Expected format: "0.9.0-beta - Foo bar." or just "0.9.0 - Foo bar." | ||
| // (We need to extract just the number for AssemblyInfo & all version for NuGet | ||
| let versionAsm, versionNuGet, releaseNotes = | ||
| let lastItem = File.ReadLines "RELEASE_NOTES.md" |> Seq.last | ||
| let firstDash = lastItem.IndexOf(" - ") | ||
| let notes = lastItem.Substring(firstDash + 2).Trim() | ||
| let version = lastItem.Substring(0, firstDash).Trim([|'*'|]).Trim() | ||
| // Get just numeric version, if it contains dash | ||
| let versionDash = version.IndexOf('-') | ||
| if versionDash = -1 then version, version, notes | ||
| else version.Substring(0, versionDash), version, notes | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Generate assembly info files with the right version & up-to-date information | ||
|
|
||
| Target "AssemblyInfo" (fun _ -> | ||
| let fileName = "src/Common/AssemblyInfo.fs" | ||
| CreateFSharpAssemblyInfo fileName | ||
| [ Attribute.Title project | ||
| Attribute.Product project | ||
| Attribute.Description summary | ||
| Attribute.Version versionAsm | ||
| Attribute.FileVersion versionAsm ] | ||
| ) | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Clean build results & restore NuGet packages | ||
|
|
||
| Target "RestorePackages" (fun _ -> | ||
| !! "./**/packages.config" | ||
| |> Seq.iter (RestorePackage (fun p -> { p with ToolPath = "./.nuget/NuGet.exe" })) | ||
| ) | ||
|
|
||
| Target "Clean" (fun _ -> | ||
| CleanDirs ["bin"; "gh-pages"; "release" ] | ||
| ) | ||
|
|
||
| Target "CleanDocs" (fun _ -> | ||
| // CleanDirs ["docs"] | ||
| () | ||
| ) | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Build library & test project | ||
|
|
||
| Target "Build" (fun _ -> | ||
| (files ["FSharp.DataFrame.sln"; "FSharp.DataFrame.Tests.sln"]) | ||
| |> MSBuildRelease "" "Rebuild" | ||
| |> ignore | ||
| ) | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Run the unit tests using test runner & kill test runner when complete | ||
|
|
||
| Target "RunTests" (fun _ -> | ||
| let nunitVersion = GetPackageVersion "packages" "NUnit.Runners" | ||
| let nunitPath = sprintf "packages/NUnit.Runners.%s/Tools" nunitVersion | ||
|
|
||
| ActivateFinalTarget "CloseTestRunner" | ||
|
|
||
| (files ["tests/*/bin/Release/FSharp.DataFrame*Tests*.dll"]) | ||
| |> NUnit (fun p -> | ||
| { p with | ||
| ToolPath = nunitPath | ||
| DisableShadowCopy = true | ||
| TimeOut = TimeSpan.FromMinutes 20. | ||
| OutputFile = "TestResults.xml" }) | ||
| ) | ||
|
|
||
| FinalTarget "CloseTestRunner" (fun _ -> | ||
| ProcessHelper.killProcess "nunit-agent.exe" | ||
| ) | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Build a NuGet package | ||
|
|
||
| Target "NuGet" (fun _ -> | ||
| // Format the description to fit on a single line (remove \r\n and double-spaces) | ||
| let description = description.Replace("\r", "").Replace("\n", "").Replace(" ", " ") | ||
| let nugetPath = ".nuget/nuget.exe" | ||
| NuGet (fun p -> | ||
| { p with | ||
| Authors = authors | ||
| Project = project | ||
| Summary = summary | ||
| Description = description | ||
| Version = versionNuGet | ||
| ReleaseNotes = releaseNotes | ||
| Tags = tags | ||
| OutputPath = "bin" | ||
| ToolPath = nugetPath | ||
| AccessKey = getBuildParamOrDefault "nugetkey" "" | ||
| Publish = hasBuildParam "nugetkey" | ||
| Dependencies = [] }) | ||
| "nuget/FSharp.DataFrame.nuspec" | ||
| ) | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Generate the documentation | ||
|
|
||
| Target "JustGenerateDocs" (fun _ -> | ||
| executeFSI "tools" "build.fsx" ["define","RELEASE"] |> ignore | ||
| ) | ||
|
|
||
| Target "GenerateDocs" DoNothing | ||
| "CleanDocs" ==> "JustGenerateDocs" ==> "GenerateDocs" | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Release Scripts | ||
|
|
||
| let gitHome = "https://github.com/BlueMountainCapital" | ||
|
|
||
| Target "ReleaseDocs" (fun _ -> | ||
| Repository.clone "" (gitHome + "/FSharp.DataFrame.git") "gh-pages" | ||
| Branches.checkoutBranch "gh-pages" "gh-pages" | ||
| CopyRecursive "docs" "gh-pages" true |> printfn "%A" | ||
| CommandHelper.runSimpleGitCommand "gh-pages" "add ." |> printfn "%s" | ||
| let cmd = sprintf """commit -a -m "Update generated documentation for version %s""" versionNuGet | ||
| CommandHelper.runSimpleGitCommand "gh-pages" cmd |> printfn "%s" | ||
| Branches.push "gh-pages" | ||
| ) | ||
|
|
||
| Target "ReleaseBinaries" (fun _ -> | ||
| Repository.clone "" (gitHome + "/FSharp.DataFrame.git") "release" | ||
| Branches.checkoutBranch "release" "release" | ||
| CopyRecursive "bin" "release/bin" true |> printfn "%A" | ||
| MoveFile "./release/" "./release/bin/FSharp.DataFrame.fsx" | ||
| let cmd = sprintf """commit -a -m "Update binaries for version %s""" versionNuGet | ||
| CommandHelper.runSimpleGitCommand "release" cmd |> printfn "%s" | ||
| Branches.push "release" | ||
| ) | ||
|
|
||
| Target "Release" DoNothing | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // Run all targets by default. Invoke 'build <Target>' to override | ||
|
|
||
| Target "All" DoNothing | ||
|
|
||
| "Clean" | ||
| ==> "RestorePackages" | ||
| ==> "AssemblyInfo" | ||
| ==> "Build" | ||
| ==> "GenerateDocs" | ||
| ==> "RunTests" | ||
| ==> "All" | ||
|
|
||
| "All" | ||
| ==> "ReleaseDocs" | ||
| ==> "ReleaseBinaries" | ||
| ==> "NuGet" | ||
| ==> "Release" | ||
|
|
||
| RunTargetOrDefault "All" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| (*** hide ***) | ||
| // This block of code is omitted in the generated HTML documentation. Use | ||
| // it to define helpers that you do not want to show in the documentation. | ||
| #I "../../bin" | ||
|
|
||
| (** | ||
| F# Project Scaffold | ||
| =================== | ||
| Documentation | ||
| <div class="row"> | ||
| <div class="span1"></div> | ||
| <div class="span6"> | ||
| <div class="well well-small" id="nuget"> | ||
| The F# DataFrame library can be <a href="https://nuget.org/packages/FSharp.ProjectTemplate">installed from NuGet</a>: | ||
| <pre>PM> Install-Package FSharp.ProjectTemplate</pre> | ||
| </div> | ||
| </div> | ||
| <div class="span1"></div> | ||
| </div> | ||
| Example | ||
| ------- | ||
| Assume we loaded [Titanic data set](http://www.kaggle.com/c/titanic-gettingStarted) | ||
| into a data frame called `titanic` (the data frame has numerous columns including string | ||
| `Sex` and Boolean `Survived`). Now we can calculate the survival rates for males and females: | ||
| *) | ||
| #r "FSharp.ProjectTemplate.dll" | ||
| open FSharp.ProjectTemplate | ||
|
|
||
| Library.hello 0 | ||
| (** | ||
| Some more info | ||
| Samples & documentation | ||
| ----------------------- | ||
| The library comes with comprehensible documentation. The tutorials and articles are | ||
| automatically generated from `*.fsx` files in [the samples folder][samples]. The API | ||
| reference is automatically generated from Markdown comments in the library implementation. | ||
| * [Stuff](stuff.html) has more stuff | ||
| * [API Reference](reference/index.html) contains automatically generated documentation for all types, modules | ||
| and functions in the library. This includes additional brief samples on using most of the | ||
| functions. | ||
| Contributing and copyright | ||
| -------------------------- | ||
| The project is hosted on [GitHub][gh] where you can [report issues][issues], fork | ||
| the project and submit pull requests. If you're adding new public API, please also | ||
| consider adding [samples][samples] that can be turned into a documentation. You might | ||
| also want to read [library design notes](design.html) to understand how it works. | ||
| The library is available under **INSERT** license, which allows modification and | ||
| redistribution for both commercial and non-commercial purposes. For more information see the | ||
| [License file][license] in the GitHub repository. | ||
| [samples]: https://github.com/fsharp/FSharp.ProjectScaffold/tree/master/samples | ||
| [gh]: https://github.com/fsharp/FSharp.ProjectScaffold | ||
| [issues]: https://github.com/fsharp/FSharp.ProjectScaffold/issues | ||
| [readme]: https://github.com/fsharp/FSharp.ProjectScaffold/blob/master/README.md | ||
| [license]: https://github.com/fsharp/FSharp.ProjectScaffold/blob/master/LICENSE.md | ||
| *) |
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| // -------------------------------------------------------------------------------------- | ||
| // Builds the documentation from `.fsx` and `.md` files in the 'docs/content' directory | ||
| // (the generated documentation is stored in the 'docs/output' directory) | ||
| // -------------------------------------------------------------------------------------- | ||
|
|
||
| #I "../../packages/FSharp.Formatting.2.0.4/lib/net40" | ||
| #r "../../packages/FAKE/tools/FakeLib.dll" | ||
| #r "FSharp.Literate.dll" | ||
| #r "FSharp.CodeFormat.dll" | ||
| #r "FSharp.MetadataFormat.dll" | ||
| open Fake | ||
| open System.IO | ||
| open Fake.FileHelper | ||
| open FSharp.Literate | ||
| open FSharp.MetadataFormat | ||
| let (++) a b = Path.Combine(a, b) | ||
|
|
||
| // Binaries that have XML documentation (in a corresponding generated XML file) | ||
| let referenceBinaries = [ "FSharp.ProjectScaffold.dll" ] | ||
| // Web site location for the generated documentation | ||
| let website = "http://tpetricek.github.io/FSharp.FSharp.ProjectScaffold" | ||
|
|
||
| // -------------------------------------------------------------------------------------- | ||
| // For typical project, no changes are needed below | ||
| // -------------------------------------------------------------------------------------- | ||
|
|
||
| // When called from 'build.fsx', use the public project URL as <root> | ||
| // otherwise, use the current 'output' directory. | ||
| #if RELEASE | ||
| let root = website | ||
| #else | ||
| let root = "file://" + (__SOURCE_DIRECTORY__ ++ "../output") | ||
| #endif | ||
|
|
||
| // Paths with template/source/output locations | ||
| let bin = __SOURCE_DIRECTORY__ ++ "../../bin" | ||
| let content = __SOURCE_DIRECTORY__ ++ "../content" | ||
| let output = __SOURCE_DIRECTORY__ ++ "../output" | ||
| let files = __SOURCE_DIRECTORY__ ++ "../files" | ||
| let template = __SOURCE_DIRECTORY__ ++ "template.html" | ||
| let referenceTemplate = __SOURCE_DIRECTORY__ ++ "reference" | ||
|
|
||
| // Build API reference from XML comments | ||
| let buildReference () = | ||
| CleanDir (output ++ "reference") | ||
| for lib in referenceBinaries do | ||
| MetadataFormat.Generate(bin ++ lib, output ++ "reference", referenceTemplate) | ||
|
|
||
| // Build documentation from `fsx` and `md` files in `docs/content` | ||
| let buildDocumentation () = | ||
| CopyRecursive files output true |> Log "Copying file: " | ||
| let subdirs = Directory.EnumerateDirectories(content, "*", SearchOption.AllDirectories) | ||
| for dir in Seq.append [content] subdirs do | ||
| let sub = if dir.Length > content.Length then dir.Substring(content.Length + 1) else "." | ||
| Literate.ProcessDirectory | ||
| ( dir, template, output ++ sub, | ||
| replacements = [ "root", root ] ) | ||
|
|
||
| // Generate | ||
| buildDocumentation() | ||
| buildReference() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <packages> | ||
| <package id="FSharp.Formatting" version="2.0.4" targetFramework="net45" /> | ||
| </packages> |
Oops, something went wrong.