Skip to content

Commit

Permalink
Update tutorials and README to mention NuGet package
Browse files Browse the repository at this point in the history
  • Loading branch information
IanWold committed Dec 14, 2018
1 parent a93a7fb commit 3cc17f2
Show file tree
Hide file tree
Showing 5 changed files with 24 additions and 11 deletions.
6 changes: 4 additions & 2 deletions Metalsharp.Documentation/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,11 @@ This quickstart will walk you through all the basics in Metalsharp. The tutorial

## Acquiring Metalsharp

You'll need a C# console application (let's call it `MyProject`). This can be either .NET Core or .NET Framework, it shouldn't matter which. You'll need to add an assembly reference to `Metalsharp.dll`, which you can only acquire by building Metalsharp from source.
You'll need a C# console application (let's call it `MyProject`). This can be either .NET Core or .NET Framework, it shouldn't matter which.This project will also, of course need a reference to Metalsharp. You can build Metalsharp from source if you like, but you can also install Metalsharp from NuGet.

When Metalsharp hits `v0.9.0-rc1`, it will be available on NuGet, but until then, you'll need to build from source and add an assembly reference.
```plaintext
PM> Install-Package Metalsharp -Version 0.9.0-rc.1
```

## Project Structure

Expand Down
8 changes: 6 additions & 2 deletions Metalsharp.Documentation/tutorial-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,11 @@ Plugins manipulate files in small and understandable ways. Metalsharp works best

Metalsharp is developed as a .NET Standard library, and your library would be the most portable if you are able to target .NET Standard as well. However, there is nothing stopping you from exclusively targeting .NET Core or Framework. If you are planning on publishing your plugin - which you definitely should - your plugin should be in a class library.

It is recommended that your plugin sit in a namespace within the `Metalsharp` namespace. In this tutorial, we'll call our version of the `Collections` plugin `MyPlugin`, so your plugin should sit in the namespace `Metalsharp.MyPlugin`. It is easiest if this is also the name of your project (for example, [`Metalsharp.FluidTemplate`](https://github.com/IanWold/Metalsharp.FluidTemplate)). This project will need an assembly reference to Metalsharp, which you must build from source. When Metalsharp reaches `v0.9.0-rc1`, it will be on NuGet, and this tutorial will be updated accordingly.
It is recommended that your plugin sit in a namespace within the `Metalsharp` namespace. In this tutorial, we'll call our version of the `Collections` plugin `MyPlugin`, so your plugin should sit in the namespace `Metalsharp.MyPlugin`. It is easiest if this is also the name of your project (for example, [`Metalsharp.FluidTemplate`](https://github.com/IanWold/Metalsharp.FluidTemplate)). This project will obviously need a reference to Metalsharp. You can build Metalsharp from source if you like, but you can also install Metalsharp from NuGet.

```plaintext
PM> Install-Package Metalsharp -Version 0.9.0-rc.1
```

### Implementing `IMetalsharpPlugin`

Expand Down Expand Up @@ -120,7 +124,7 @@ If you want to keep your source closed (or if you're in an enterprise and you ne

**NuGet**

NuGet is the de facto package manager for .NET, and that's how Metalsharp will eventually be released. Indeed, until Metalsharp is on NuGet it doesn't make sense to release here. But that's coming around the corner, so preparing your package for NuGet might make sense. And, it'll give other users an easier time consuming your plugin.
NuGet is the de facto package manager for .NET, and that's how Metalsharp is released. Releasing your package on NuGet gives other users an easier time consuming your plugin. If you are planning on releasing your plugin on NuGet, it's best practice for your C# project to reference Metalsharp from NuGet.

**DLL Download**

Expand Down
8 changes: 4 additions & 4 deletions Metalsharp.Documentation/tutorial-website.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@ This tutorial will walk you through (almost) all the components of Metalsharp yo
The website we'll be making will have a homepage, a few text pages, and several blog posts. We'll use the [Metalsharp.FluidTemplate](https://github.com/IanWold/Metalsharp.FluidTemplate) plugin to use templates for our site. First, we'll walk through adding each of the pages and the design decisions behind doing things the way they are presented (hopefully allowing you to easier change this structure if you desire). Then, we'll write the Metalsharp code to do all the generation.

> **Please Note:** Until `v0.9.0-rc1`, Metalsharp won't be able to be installed via NuGet. You'll need to build it from source yourself.
## Content

* [Project Files](https://github.com/IanWold/Metalsharp/blob/master/Metalsharp.Documentation/tutorial-website.md#project-files)
Expand Down Expand Up @@ -132,9 +130,11 @@ This concludes all of the files for the website project. You will, in addition,

To start using Metalsharp, you'll need a new C# console application. Metalsharp is written in .NET Standard, so you can choose whether you want to create a .NET Framework or a .NET Core console application. In general, if you are running Windows and you will need to rely on the robustness and future-compatibility of .NET Framework (this would probably be in an enterprise environment), then choose .NET Framework. Otherwise, Microsoft really wants you to choose .NET Core. This tutorial will use .NET Core, though it will (probably) make no difference to you. We'll call the C# app `MyProject`.

> When Metalsharp is on NuGet, you will also have the option of using a C# script with NuGet packages (via [scriptcs](http://scriptcs.net/)) to create your project. Until then, this tutorial will only cover a C# project. In addition, you will currently need to build Metalsharp from source and add an assembly reference to your built DLL. This tutorial will be updated when Metalsharp hits NuGet.
Your project will have a `Program.cs` file with a `Main` method inside. In the main method, we will instantiate a `MetalsharpProject` object, add our files, apply several plugins to it, and built it to an output directory. Each step of the way this tutorial will explain parts of the Metalsharp API. Full generated API documentation [is available here](https://github.com/IanWold/Metalsharp/blob/master/Metalsharp.Documentation/api.md). This project will also, of course need a reference to Metalsharp. You can build Metalsharp from source if you like, but you can also install Metalsharp from NuGet.

Your project will have a `Program.cs` file with a `Main` method inside. In the main method, we will instantiate a `MetalsharpProject` object, add our files, apply several plugins to it, and built it to an output directory. Each step of the way this tutorial will explain parts of the Metalsharp API. Full generated API documentation [is available here](https://github.com/IanWold/Metalsharp/blob/master/Metalsharp.Documentation/api.md).
```plaintext
PM> Install-Package Metalsharp -Version 0.9.0-rc.1
```

### Adding files

Expand Down
1 change: 1 addition & 0 deletions Metalsharp/Metalsharp.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
<RepositoryType>Git</RepositoryType>
<PackageTags>metalsharp metalsmith static-site-generator static-site dotnet-standard</PackageTags>
<PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
<Description>A tiny and extendable C# library for generating static sites, inspired by Metalsmith.</Description>
</PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
Expand Down
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,14 @@ new MetalsharpDirectory("Site")

## Getting Started

To get Metalsharp, you can either build it from source, or get it on [NuGet](https://www.nuget.org/packages/Metalsharp/).

```plaintext
PM> Install-Package Metalsharp -Version 0.9.0-rc.1
```

> Note that you will need NuGet 4.3.0 or higher to install Metalsharp with NuGet.
### Configuring a Metalsharp Project Directory

It is recommended that a Metalsharp project use something like the following directory structure.
Expand Down Expand Up @@ -115,9 +123,7 @@ If you'd like to contribute, please do! Open an Issue, submit a PR, I'm happy ho

## Roadmap

The current objective is to get to `v0.9.0-rc1`. As of 13 December 2018 all the boxes have been checked to this end, and to this end all the last-minute reviews are being done so we can publish on NuGet. This involves making sure we have the test coverage we want, naming concerns are all sorted out, functionality is all useful, and documentation is current. We're targeting 16 December as the deadline for the NuGet release.

After `v0.9.0-rc1` is released to Nuget, the goal is to test the library thoroughly in as many situations as possible to be sure of its design and usability. This will involve generating a GitHub Pages homepage for Metalsharp, and it may involve writing integration tests. `v0.9.0` will be released to Nuget when there is a concensus that Metalsharp is designed correctly.
`v0.9.0-rc.1` is on NuGet! The current goal is to test the library thoroughly in as many situations as possible to be sure of its design and usability. This will involve generating a GitHub Pages homepage for Metalsharp, and it may involve writing integration tests. `v0.9.0` will be released to Nuget when there is a concensus that Metalsharp is designed correctly.

After `v0.9.0`, it's on to `v1.0.0`!

Expand Down

0 comments on commit 3cc17f2

Please sign in to comment.