dungpa / FSharp.ProjectScaffold

A prototypical F# library (file system layout and tooling), recommended by the F# Foundation.

FSharp.ProjectScaffold

A prototypical F# library (file system layout and tooling), recommended by the F# Foundation.

This sample demonstrates the suggested structure of a typical F# solution. (NOTE: this layout should NOT be used when authoring a Type Provider. For more details about doing so, please read this.) It also showcase a few popular F#-centric libraries (e.g. F# Make), as well as using some more general libraries (e.g. NUnit) from within F#.

---

Summary of solution folders

Folder	Descritpion
.nuget	This directory, and the files it contains, are used to bootstrap the build process. Specifically, it enables the acquistion of NuGet dependencies on a clean build. It is further used by the build process when performing other NuGet-related tasks. These tools also facilitate the Package Restore functionality inside of Visual Studio. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory be committed to source control.
bin	This directory is the primary output directory for libraries and NuGet packages when using the build system (i.e. build.cmd or build.fsx). It is also the target directory when building in Release mode inside Visual Studio (Note: this has to me manually configured on a per-project basis, as has been done with the example project). This directory is touched by many parts of the build process. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory NOT be committed to source control.
docs/content	Use this directory for all your narratvie documentation source files. Said files should be either F# scripts (ending in .fsx) or Mark Down files (ending in .md). This project includes two sample scripts. Feel free to extend and/or replace these files. For more information on generating documentation, please see FSharp.Formatting.
docs/files	Use this directory to house any supporting assets needed for documentation generation. For instance, this directory might be where you place image files which are to be linked/embedded in the final documentation.
docs/output	This directory will contain the final artifacts for both narrative and API documentation. This folder will be automatically created by the documenation generation process. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory NOT be committed to source control.
docs/tools	This directory contains tools used in the generation of both narrative documentation and API documentation. The main interaction with the content of this directory consists of editing generate.fsx to include the appropriate repository information (see the following table for more details).
docs/tools/templates	This directory contains the (default) Razor template used as part of generating documentation. You are encouraged to edit this template. You may also create additional templates, but that will require making edits to generate.fsx.
lib	Any libraries on which your project depends and which are NOT managed via NuGet should be kept in this directory. This typically includes custom builds of third-party software, private (i.e. to a company) codebases, and native libraries.
nuget	You should use this directory to store any artifacts required to produce a NuGet package for your project. This typically includes a .nuspec file and some .ps1 scripts, for instance. Additionally, this example project includes a .cmd file suitable for manual deployment of packages to http://nuget.org.
packages	Any NuGet packages on which your project depends will be downloaded to this directory. Additionally, packages required by the build process will be stored here. It is strongly advised that the contents of this directory NOT be committed to source control.
src	Use this directory to house the actual codebase (e.g. one, or more, Visual Studio F# projects) in your solution. A good way to get started is to rename the project included in this sample (FSharp.ProjectTemplate). Alternately, delete the sample project and create your own. NOTE: When you rename the sample project, or add aditional projects to this directory, you may need to edit build.fsx and/or generate.fsx. You will, likely, also need to update your .sln file(s). Please see the following table for more details. NOTE: you should NOT place testing porjects in this path. Testing files belong in the tests directory.
temp	This directory is used by the build process as a "scratch", or working, area. It is strongly recommended that nothing be put into this directory. It is strongly advised that the contents of this directory NOT be committed to source control.
tests	Use this directory to house any testing projects you might develop (i.e. libraries leveraging NUnit, xUnit, MBUnit, et cetera). The sample project included in this directory is configured to use NUnit. Further, build.fsx is coded to execute these test as part of the build process. NOTE: When you rename the sample project, or add aditional projects to this directory, you may need to edit build.fsx and/or generate.fsx. You will, likely, also need to update your .sln file(s). Please see the following table for more details.

Summary of important solution files

Path	Descritpion
build.cmd	A simple command script which allows the build to be started (i.e. calls build.fsx) from the command prompt or the file system explorer. It also fetches the latest version of F# Make, if it's not detected in packages.
build.fsx	This very important file runs the build process. It uses the F# Make library to manage many aspects of maintaining a solution. It contains a number of common tasks (i.e. build targets) such as directory cleaning, unit test execution, and NuGet package assembly. You are encouraged to adapt existing build targets and/or add new ones as necessary. However, if you are leveraging the default conventions, as setup in this scaffold project, you can start by simply supplying some values at the top of this file. They are as follows: project The name of your project, which is used in serveral places: in the generation of AssemblyInfo, as the name of a NuGet package, and for locating a directory under src. summary A short summary of your project, used as the description in AssemblyInfo. It also provides as a short summary for your NuGet package. description A longer description of the project used as a description for your NuGet package (Note: line breaks are automatically cleaned up). authors A list of authors' names, as should be displayed in the NuGet package metadata. tags A string containing space-separated tags, as should be included in the NuGet package metadata. solutionFile The name of your solution file (sans-extension). It is used as part of the build process. testAssemblies A list of F# Make globbing patterns to be searched for unit-test assemblies. gitHome The URL of user profile hosting this project's GitHub repository. This is used for publishing documentation. gitName The name of this project's GitHub repository. This is used for publishing documentation. TODO: document list of included build targets.
FSharp.ProjectScaffold.sln	This is a standard Visual Studio solution file. Use it to collect you projects, including tests. Additionally, this example solution includes many of the important non-project files. It is compatible with Visual Studio 2012 and Visual Studio 2013.
LICENSE.txt	This file contains all the relevant legal-ese for your project.
RELEASE_NOTES.md	This file details verion-by-version changes in your code. It is used for documentation and to populate nuget package details. It uses a proper subset of MarkDown, with a few simple conventions. More details of this format may be found in the documenation for F# Make's ReleaseNotesHelper.
README.md	Use this file to provide an overview of your repository.
docs/content/index.fsx	Use this file to provide a narrative overview of your project. You can write actual, executable F# code in this file. Additionally, you may use MarkDown comments. As part of the build process, this file (along with any other *.fsx or *.md files in the docs/content directory) will be processed into HTML documentation. There is also a build target to deploy the generated documentation to a GitHub pages branch (assuming one has been setup in your repository). For further details about documentation generation, please see the FSharp.Formatting library.
docs/content/tutorial.fsx	This file follows the format of docs/content/index.fsx. It's mainly included to demonstrate that narrative documenation is not limited to a single file, and documentation files maybe hyperlinked to one another.
docs/tools/generate.fsx	This file controls the generation of narrative and API documentation. In most projects, you'll simply need to edit some values located at the top of the file. They are as follows: referenceBinaries A list of the binaries for which documentation should be cretaed. The files listed should each have a corresponding XMLDoc file, and reside in the bin folder (as handled by the build process). website The root URL to which generated documenation should be uploaded. In the included example, this points to the GitHub Pages root for this project. info A list of key/value pairs which further describe the details of your project. This list is exposed to template.cshtml for data-binding purposes. You may include any information deemed necessary. Note: the pairs defined in the included example are being used by the sample template.
docs/tools/templates/template.cshtml	This file provides the basic HTML layout for generated documentation. It uses the C# variant of the Razor templating engine, and leverages jQuery and Bootstrap. Change this file to alter the non-content portions of your documentation. Note: Much of the data passed to this template (i.e. items preceeded with '@') is configured in generate.fsx

---

Sample API documents available here.