From 78a7aca1441fad2f413fcdd8a391f9c1319d6d2a Mon Sep 17 00:00:00 2001 From: Christoph Ruegg Date: Sun, 15 Feb 2015 13:58:07 +0100 Subject: [PATCH] Docs: tweak build & tools docs, merge into website --- CONTRIBUTORS.md | 2 +- MathNet.Numerics.sln | 1 + build.fsx | 3 +- docs/content/Build.md | 143 +++++++++++++++++++++++++++ docs/content/index.fsx | 91 +++++------------ docs/tools/build-docs.fsx | 2 +- docs/tools/templates/template.cshtml | 9 +- 7 files changed, 180 insertions(+), 71 deletions(-) create mode 100644 docs/content/Build.md diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 83dae87b..ecae6d21 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -7,7 +7,7 @@ The Math.NET project is a community effort. We accept contributions and pull req ### Maintainers -- [Christoph Rüegg](http://christoph.ruegg.name/) (@cdrnet) +- [Christoph Rüegg](http://christoph.ruegg.name/) (@cdrnet) ([keybase.io/cdrnet](https://keybase.io/cdrnet)) ### Code Contributors diff --git a/MathNet.Numerics.sln b/MathNet.Numerics.sln index 307b0cf7..b123719a 100644 --- a/MathNet.Numerics.sln +++ b/MathNet.Numerics.sln @@ -35,6 +35,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Build", "Build", "{A4A66FA9 EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{039229DA-AFDA-48DB-B7FC-B064691DEE96}" ProjectSection(SolutionItems) = preProject + docs\content\Build.md = docs\content\Build.md docs\content\CSV.fsx = docs\content\CSV.fsx docs\content\DescriptiveStatistics.fsx = docs\content\DescriptiveStatistics.fsx docs\content\Distance.fsx = docs\content\Distance.fsx diff --git a/build.fsx b/build.fsx index ef9dfcc9..7ebda9e7 100644 --- a/build.fsx +++ b/build.fsx @@ -665,8 +665,7 @@ Target "PublishMirrors" (fun _ -> Target "PublishDocs" (fun _ -> let repo = "../mathnet-websites" Git.Branches.pull repo "origin" "master" - CleanDir "../mathnet-websites/numerics/docs" - CopyRecursive "out/docs" "../mathnet-websites/numerics/docs" true |> printfn "%A" + CopyRecursive "out/docs" "../mathnet-websites/numerics" true |> printfn "%A" Git.Staging.StageAll repo Git.Commit.Commit repo (sprintf "Numerics: %s docs update" packageVersion) Git.Branches.pushBranch repo "origin" "master") diff --git a/docs/content/Build.md b/docs/content/Build.md new file mode 100644 index 00000000..56e930f1 --- /dev/null +++ b/docs/content/Build.md @@ -0,0 +1,143 @@ +Building Math.NET Numerics +========================== + +If you do not want to use the official binaries, or if you like to modify, +debug or contribute, you can compile locally either using Visual Studio or +manually with the build scripts. + +VisualStudio or Xamarin Studio +------------------------------ + +The Visual Studio solutions should build out of the box, without any preparation +steps or package restores. Tests can be run with the usual integrated NUnit test +runners or ReSharper. + +MSBuild or XBuild +----------------- + +Instead of a compatible IDE you can also build the solutions directly with +`msbuild`, or on Mono with `xbuild`. + + msbuild MathNet.Numerics.sln # only build for .Net 4 (main solution) + msbuild MathNet.Numerics.Net35Only.sln # only build for .Net 3.5 + msbuild MathNet.Numerics.All.sln # full build with .Net 4, 3.5 and PCL profiles + xbuild MathNet.Numerics.sln # build with Mono, e.g. on Linux or Mac + +FAKE +---- + +The fully automated build including unit tests, documentation and api +reference, NuGet and Zip packages is using [FAKE](http://fsharp.github.io/FAKE/). + +FAKE itself is not included in the repository but it will download and bootstrap +itself automatically when build.cmd is run the first time. Note that this step +is *not* required when using Visual Studio or `msbuild` directly. + + build.cmd # normal build (.Net 4.0), run unit tests (.Net on Windows) + ./build.sh # normal build (.Net 4.0), run unit tests (Mono on Linux/Mac, .Net on Windows) + + build.cmd Build # normal build (.Net 4.0) + build.cmd Build incremental # normal build, incremental (.Net 4.0) + build.cmd Build all # full build (.Net 4.0, 3.5, PCL) + build.cmd Build net35 # compatibility build (.Net 3.5 + build.cmd Build signed # normal build, signed/strong named (.Net 4.0) + + build.cmd Test # normal build (.Net 4.0), run unit tests + build.cmd Test quick # normal build (.Net 4.0), run unit tests except long running ones + build.cmd Test all # full build (.Net 4.0, 3.5, PCL), run all unit tests + build.cmd Test net35 # compatibility build (.Net 3.5), run unit tests + + build.cmd Clean # cleanup build artifacts + build.cmd Docs # generate documentation + build.cmd Api # generate api reference + build.cmd Zip # generate zip packages (.Net 4.0) + build.cmd NuGet # generate NuGet packages (.Net 4.0) + build.cmd NuGet all # generate normal NuGet packages (.Net 4.0, 3.5, PCL) + build.cmd NuGet signed # generate signed/strong named NuGet packages (.Net 4.0) + + build.cmd All # build, test, docs, api reference (.Net 4.0) + +If the build or tests fail claiming that FSharp.Core was not be found, see +[fsharp.org](http://fsharp.org/use/windows/) or install the +[Visual F# 3.0 Tools](http://go.microsoft.com/fwlink/?LinkId=261286) directly. + +Creating a Release +------------------ + +While only maintainers can make official releases published on NuGet and +referred to from the website, you can use the same tools to make your own +releases for your own purposes. + +Versioning is controlled by the release notes. Before building a new version, +first add a new release header and change notes on top of the `RELEASENOTES.md` +document in the root directory. The fake builds pick this up and propagate it +to the assembly info files automatically. + +The build can then be launched by calling: + + build.sh All release # full release build + build.sh NuGet release # if you only need NuGet packages + build.sh Zip release # if you only need Zip packages + +The build script will print the current version as part of the the header banner, +which is also included in the release notes document in the build artifacts. +Example: + + // __ __ _ _ _ _ ______ _______ + // | \/ | | | | | | \ | | ____|__ __| + // | \ / | __ _| |_| |__ | \| | |__ | | + // | |\/| |/ _` | __| '_ \ | . ` | __| | | + // | | | | (_| | |_| | | |_| |\ | |____ | | + // |_| |_|\__,_|\__|_| |_(_)_| \_|______| |_| + // + // Math.NET Numerics - http://numerics.mathdotnet.com + // Copyright (c) Math.NET - Open Source MIT/X11 License + // + // Math.NET Numerics v3.5.0 + // Math.NET Numerics MKL Provider v1.7.0 + // Math.NET Numerics Data Extensions v3.1.0 + +The artifacts are then ready in the `out/packages` directory. + +Extra Packages +-------------- + +In addition to the core package this repository also include extra packages +like the MKL provider and the data extensions. Most build targets are available for +these packages as well, with the following prefixes: + +* `Mkl` for the MKL provider (`MklWin` or `MklLinux` if platform dependent) +* `Data` for the Data Extensions + +Example: `build.sh MklWinNuget release` + +Official Release Process (Maintainers only) +------------------------------------------- + +* Update `RELEASENOTES.md` file with relevant changes, attributed by contributor (if external). Set date. +* Update `CONTRIBUTORS.md` file (via `git shortlog -sn`) + +* Build Release: + + build.sh All release + +* Commit and push release notes and (auto-updated) assembly info files with new "Release: v1.2.3" commit + +* Publish Release: + + build.sh PublishDocs + build.sh PublishApi + build.sh PublishTag + build.sh PublishMirrors + build.sh PublishNuGet + + In theory there is also a `Publish` target to do this in one step, unfortunately + publishing to the NuGet gallery is quite unreliable. + +* Create new Codeplex and GitHub release, attach Zip files (to be automated) +* Copy artifacts to [release archive](http://1drv.ms/1lMtdNi) (to be automated) +* Consider a tweet via [@MathDotNet](https://twitter.com/MathDotNet) +* Consider a post to the [Google+ site](https://plus.google.com/112484567926928665204) +* Update Wikipedia release version and date for the + [Math.NET Numerics](http://en.wikipedia.org/wiki/Math.NET_Numerics) and + [Comparison of numerical analysis software](http://en.wikipedia.org/wiki/Comparison_of_numerical_analysis_software) articles. diff --git a/docs/content/index.fsx b/docs/content/index.fsx index e6c8b9df..cec38b44 100644 --- a/docs/content/index.fsx +++ b/docs/content/index.fsx @@ -4,31 +4,46 @@ #r "MathNet.Numerics.FSharp.dll" (** -Getting Started -=============== +Math.NET Numerics +================= + +Math.NET Numerics aims to provide methods and algorithms for numerical computations +in science, engineering and every day use. Covered topics include special functions, +linear algebra, probability models, random numbers, interpolation, integration, +regression, optimization problems and more. + +Math.NET Numerics is part of the [Math.NET initiative](http://www.mathdotnet.com/) +and is the result of merging dnAnalytics with Math.NET Iridium, replacing both. +It targets Microsoft .Net 4, .Net 3.5 and Mono (Windows, Linux and Mac), +Silverlight 5, WindowsPhone 8, Windows 8/Store (PCL 47, 136) and Android/iOS (Xamarin). +In addition to a purely managed implementation it also supports native hardware +optimization. Available for free under the [MIT/X11 License](License.html). NuGet Packages -------------- -The recommended way to get Math.NET Numerics is to use NuGet. The following packages are provided and maintained in the public [NuGet Gallery](https://nuget.org/profiles/mathnet/). -Alternatively you can also download the binaries in Zip packages, available on [CodePlex](http://mathnetnumerics.codeplex.com/releases). +The recommended way to get Math.NET Numerics is to use NuGet. The following +packages are provided and maintained in the public +[NuGet Gallery](https://nuget.org/profiles/mathnet/). +Alternatively you can also download the binaries in Zip packages, available on +[CodePlex](http://mathnetnumerics.codeplex.com/releases). Core Package: -- **MathNet.Numerics** - core package, including .Net 4, .Net 3.5 and portable/PCL builds. -- **MathNet.Numerics.FSharp** - optional extensions for a better F# experience. BigRational. -- **MathNet.Numerics.Signed** - strong-named version of the core package *(not recommended)*. -- **MathNet.Numerics.FSharp.Signed** - strong-named version of the F# package *(not recommended)*. +- [**MathNet.Numerics**](https://www.nuget.org/packages/MathNet.Numerics/) - core package, including .Net 4, .Net 3.5 and portable/PCL builds. +- [**MathNet.Numerics.FSharp**](https://www.nuget.org/packages/MathNet.Numerics.FSharp/) - optional extensions for a better F# experience. BigRational. +- [**MathNet.Numerics.Signed**](https://www.nuget.org/packages/MathNet.Numerics.Signed/) - strong-named version of the core package *(not recommended)*. +- [**MathNet.Numerics.FSharp.Signed**](https://www.nuget.org/packages/MathNet.Numerics.FSharp.Signed/) - strong-named version of the F# package *(not recommended)*. Alternative Provider Packages (optional): -- **MathNet.Numerics.MKL.Win-x86** - Native Intel MKL Linear Algebra provider (Windows/32-bit). -- **MathNet.Numerics.MKL.Win-x64** - Native Intel MKL Linear Algebra provider (Windows/64-bit). +- [**MathNet.Numerics.MKL.Win-x86**](https://www.nuget.org/packages/MathNet.Numerics.MKL.Win-x86/) - Native Intel MKL Linear Algebra provider (Windows/32-bit). +- [**MathNet.Numerics.MKL.Win-x64**](https://www.nuget.org/packages/MathNet.Numerics.MKL.Win-x64/) - Native Intel MKL Linear Algebra provider (Windows/64-bit). Data/IO Packages for reading and writing data (optional): -- **MathNet.Numerics.Data.Text** - Text-based matrix formats like CSV and MatrixMarket. -- **MathNet.Numerics.Data.Matlab** - MATLAB Level-5 matrix file format. +- [**MathNet.Numerics.Data.Text**](https://www.nuget.org/packages/MathNet.Numerics.Data.Text/) - Text-based matrix formats like CSV and MatrixMarket. +- [**MathNet.Numerics.Data.Matlab**](https://www.nuget.org/packages/MathNet.Numerics.Data.Matlab/) - MATLAB Level-5 matrix file format. Platform Support and Dependencies @@ -200,56 +215,4 @@ Which will print something like the following to the output: See [Intel MKL](MKL.html) for details how to use native providers on Linux. - -Building Math.NET Numerics --------------------------- - -If you do not want to use the official binaries, or if you like to modify, debug or contribute, you can compile Math.NET Numerics locally either using Visual Studio or manually with the build scripts. - -* The Visual Studio solutions should build out of the box, without any preparation steps or package restores. -* Instead of a compatible IDE you can also build the solutions with `msbuild`, or on Mono with `xbuild`. -* The full build including unit tests, docs, NuGet and Zip packages is using [FAKE](http://fsharp.github.io/FAKE/). - -### How to build with MSBuild/XBuild - - [lang=sh] - msbuild MathNet.Numerics.sln # only build for .Net 4 (main solution) - msbuild MathNet.Numerics.Net35Only.sln # only build for .Net 3.5 - msbuild MathNet.Numerics.All.sln # full build with .Net 4, 3.5 and PCL profiles - xbuild MathNet.Numerics.sln # build with Mono, e.g. on Linux or Mac - -### How to build with FAKE - - [lang=sh] - build.cmd # normal build (.Net 4.0), run unit tests (.Net on Windows) - ./build.sh # normal build (.Net 4.0), run unit tests (Mono on Linux/Mac, .Net on Windows) - - build.cmd Build # normal build (.Net 4.0) - build.cmd Build incremental # normal build, incremental (.Net 4.0) - build.cmd Build all # full build (.Net 4.0, 3.5, PCL) - build.cmd Build net35 # compatibility build (.Net 3.5 - build.cmd Build signed # normal build, signed/strong named (.Net 4.0) - - build.cmd Test # normal build (.Net 4.0), run unit tests - build.cmd Test quick # normal build (.Net 4.0), run unit tests except long running ones - build.cmd Test all # full build (.Net 4.0, 3.5, PCL), run all unit tests - build.cmd Test net35 # compatibility build (.Net 3.5), run unit tests - - build.cmd Clean # cleanup build artifacts - build.cmd Docs # generate documentation - build.cmd Api # generate api reference - - build.cmd NuGet all # generate normal NuGet packages (.Net 4.0, 3.5, PCL) - build.cmd NuGet signed # generate signed/strong named NuGet packages (.Net 4.0) - - build.cmd NativeBuild # build native providers for all platforms - build.cmd NativeTest # test native providers for all platforms - - build.cmd All # build, test, docs, api reference (.Net 4.0) - build.cmd All release # release build - -FAKE itself is not included in the repository but it will download and bootstrap itself automatically when build.cmd is run the first time. Note that this step is *not* required when using Visual Studio or `msbuild` directly. - -If the build or tests fail claiming that FSharp.Core was not be found, see [fsharp.org](http://fsharp.org/use/windows/) or install the [Visual F# 3.0 Tools](http://go.microsoft.com/fwlink/?LinkId=261286) directly. - *) diff --git a/docs/tools/build-docs.fsx b/docs/tools/build-docs.fsx index 4ad602d6..1ab826e6 100644 --- a/docs/tools/build-docs.fsx +++ b/docs/tools/build-docs.fsx @@ -6,7 +6,7 @@ // Binaries that have XML documentation (in a corresponding generated XML file) let referenceBinaries = [ "MathNet.Numerics.dll"; "MathNet.Numerics.FSharp.dll" ] // Web site location for the generated documentation -let website = "http://numerics.mathdotnet.com/docs" +let website = "http://numerics.mathdotnet.com" let githubLink = "http://github.com/mathnet/mathnet-numerics" // Specify more information about your project diff --git a/docs/tools/templates/template.cshtml b/docs/tools/templates/template.cshtml index 315217af..009244fe 100644 --- a/docs/tools/templates/template.cshtml +++ b/docs/tools/templates/template.cshtml @@ -47,13 +47,16 @@
  • Project Website
  • Release Notes
  • MIT/X11 License
    • -
  • Contributors
    • -
  • Contributing
  • Class Reference
  • Issues & Bugs
    • -
  • Your Ideas
  • Who is using Math.NET?
    • +
  • Contributing
    • +
  • Contributors
    • +
  • Contributing
    • +
  • Build & Tools
    • +
  • Your Ideas
    • +
  • Getting Help
  • Stack Overflow
  • Discuss