Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/colinbull/officeprovider

A type provider over docx and xlsx documents
https://github.com/colinbull/officeprovider

Last synced: 20 days ago
JSON representation

A type provider over docx and xlsx documents

Host: GitHub
URL: https://github.com/colinbull/officeprovider
Owner: colinbull
License: apache-2.0
Created: 2014-09-09T07:09:59.000Z (over 10 years ago)
Default Branch: master
Last Pushed: 2018-03-02T11:56:23.000Z (almost 7 years ago)
Last Synced: 2024-11-08T07:07:49.267Z (2 months ago)
Language: F#
Size: 3.03 MB
Stars: 1
Watchers: 1
Forks: 2
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

F# ProjectScaffold
=======================

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

This scaffolding can be used to generate the suggested structure of a typical F# library.
_(NOTE: this layout needs adjusting when authoring a Type Provider.
For more details about doing so, please [read this.](../../wiki/Suggestions-for-Building-a-Type-Provider))_

### Technologies

| Area | Technologies |
|:--------------------------|:------------------------------------------|
| Platforms | Linux, Windows, OSX |
| Build Automation | [FAKE](http://fsharp.github.io/FAKE/) |
| Unit Testing | [NUnit](http://www.nunit.org/) |
| Package Formats | Nuget packages |
| Documentation Authoring | Markdown, HTML and F# Literate Scripts |
| Source Code Linking | SourceLink |
| Continuous Build and Test | [Travis](http://travis-ci.org) (Linux/OSX) and [AppVeyor](http://appveyor.com) (Windows) |
| Default Package Hosting | [nuget.org](http://nuget.org) |
| Default Documentation Hosting | [GitHub Pages](https://help.github.com/articles/what-are-github-pages) |

### Initializing

Run

./build.sh
or

./build.cmd

You will be prompted for the name of your project and some other details. The project structure will then be generated from templates.

### Build and Release

After initialization, you can

- Open, edit, build and test using ``ProjectName.sln``
- Build and test release binaries using ``build.cmd`` or ``build.sh ``
- Build and test release packages using ``build.cmd Release`` or ``build.sh Release``
- Build and publish release docs using ``build.cmd ReleaseDocs`` or ``build.sh ReleaseDocs``
- Publish packages using ``nuget/publish.cmd``

### Structure

Summary of solution folders

Folder
Description

.nuget

These files are used to get NuGet dependencies on a clean build and for other NuGet-related tasks including
Package Restore of Visual Studio.

Do not put anything else in this directory.

Do commit the contents of this directory to source control.

bin

The primary output directory for libraries and NuGet packages when using the build system
(i.e. build.cmd and build.sh). It is also the target directory when building in Visual Studio or Xamarin Studio
(Note: this has to be manually configured on a per-project basis, as has been done with the example project).

Do not put anything else in this directory.

Do not commit the contents of this directory to source control.

docs/content

Use this directory for all your literate documentation source files.
These should be either F# scripts (ending in .fsx) or Markdown files (ending in .md).
This project includes two sample documentation scripts. Feel free to extend and/or replace these files.
For more information on generating documentation, please see FSharp.Formatting.

docs/files

Contains supporting assets needed for documentation generation.
For instance, image files which are to be linked/embedded in the final documentation.

docs/output

Contains the final artifacts for both narrative and API documentation.
This folder will be automatically created by the documenation generation process.

Do not put anything else in this directory.

Do not commit this directory to source control.

docs/tools

Contains tools used in the generation of both narrative documentation and API documentation.
Edit generate.fsx to include the appropriate repository information
(see the following table for more details).

docs/tools/templates

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

Stores the NuGet package specifications for your project, typically a .nuspec file.
Also includes a publish.cmd file for manual deployment of packages to http://nuget.org.

packages

Contains any NuGet packages on which your project depends will be downloaded to this directory.

Do not put anything else in this directory.

Do not commit the contents of this directory to source control.

src

The actual codebase (e.g. one, or more, F# projects) in your solution.
The project files are automatically renamed from (FSharp.ProjectTemplate) when initializing the project.

NOTE: When you add projects to this directory, you will need to edit build.fsx and/or generate.fsx.
You will also need to update your .sln file(s).

NOTE: Do not place testing projects 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.

Do not put anything else in this directory.

Do not commit the contents of this directory to source control.

tests

Contains 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 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).

### Files

Summary of important solution files

Path
Descritpion

.travis.yml

Specifies an automated continuous integration (CI) build-and-test on OSX using Travis. Enable your CI build at
travis-ci.org by logging on there wih your GitHub account and
activating the project. If you enable this, then every pull request, commit, branch and tag
of your project on GitHub will be built automatically. Builds of open source projects are free. The default
build is on Mac OSX (you can also specify Linux by changing the default language).

appveyor.yml

A specification of an automated continuous integration (CI) build-and-test on Windows using AppVeyor.
Enable your CI build at appveyor.com.

build.cmd and build.sh

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.