Rhodes documentation map

build-appveyor.bat

@@ -6,6 +6,7 @@ ECHO ~~~~~~~~~~~~~~~~~~~ %~f0 ~~~~~~~~~~~~~~~~~~~
 SET ROOTDIR=%CD%
 SET PATH=C:\Program Files (x86)\MSBuild\14.0\Bin;%PATH%
 SET PATH=%CD%\scriptcs;%PATH%
+SET PATH=%CD%\docfx;%PATH%
 
 FOR /F "tokens=*" %%i in ('powershell Get-ExecutionPolicy') do SET PSPOLICY=%%i
 ECHO Powershell execution policy^: %PSPOLICY%

scripts/build-docs.sh

@@ -0,0 +1,12 @@
+set -eu
+
+echo docfx needs mono-devel to run
+
+if [ ! -f "docfx.zip" ]; then curl -o docfx.zip -L https://github.com/dotnet/docfx/releases/download/v2.15.1/docfx.zip; fi
+if [ ! -d "docfx" ]; then mkdir -p docfx && unzip -o docfx.zip -d docfx; fi
+
+#Generating docs in one step ('docfx.exe docfx.json') fails with:
+#System.Reflection.ReflectionTypeLoadException
+#splitting in two steps works
+mono ./docfx/docfx.exe metadata ./src/Documentation/docfx.json
+mono ./docfx/docfx.exe build ./src/Documentatio/docfx.json

scripts/build.csx

@@ -8,9 +8,9 @@ using System.Text;
 using System.Text.RegularExpressions;
 
 string access_token = Environment.GetEnvironmentVariable("MAPBOX_ACCESS_TOKEN");
-if(string.IsNullOrWhiteSpace(access_token)){
-    Console.Error.WriteLine("%MAPBOX_ACCESS_TOKEN% not set - cannot run tests");
-    Environment.Exit(1);
+if (string.IsNullOrWhiteSpace(access_token)) {
+	Console.Error.WriteLine("%MAPBOX_ACCESS_TOKEN% not set - cannot run tests");
+	Environment.Exit(1);
 }
 
 //ATTENTION: latest version of `srciptcs` seems to change the current directory
@@ -20,6 +20,8 @@ Console.WriteLine("cwd [build.csx]: {0}", Directory.GetCurrentDirectory());
 Directory.SetCurrentDirectory(rootDir);
 Console.WriteLine("cwd [build.csx]: {0}", Directory.GetCurrentDirectory());
 string commitMessage = Environment.GetEnvironmentVariable("APPVEYOR_REPO_COMMIT_MESSAGE");
+string commitMessageEx = Environment.GetEnvironmentVariable("APPVEYOR_REPO_COMMIT_MESSAGE_EXTENDED");
+if (!string.IsNullOrWhiteSpace(commitMessageEx)) { commitMessage += " " + commitMessageEx; }
 Console.WriteLine("commit message: \"{0}\"", commitMessage);
 
 string configuration = Environment.GetEnvironmentVariable("configuration");
@@ -35,35 +37,30 @@ if (publishNuget) { Console.WriteLine("going to publish to nuget.org"); }
 if (publishDocs) { Console.WriteLine("going to publish docs"); }
 
 string nugetApiKey;
-if (publishNuget)
-{
-    nugetApiKey = Environment.GetEnvironmentVariable("NUGET_API_KEY");
-    if (string.IsNullOrWhiteSpace(nugetApiKey))
-    {
-        Console.Error.WriteLine("cannot publish to nuget.org without %NUGET_API_KEY%");
-        Environment.Exit(1);
-    }
+if (publishNuget) {
+	nugetApiKey = Environment.GetEnvironmentVariable("NUGET_API_KEY");
+	if (string.IsNullOrWhiteSpace(nugetApiKey)) {
+		Console.Error.WriteLine("cannot publish to nuget.org without %NUGET_API_KEY%");
+		Environment.Exit(1);
+	}
 }
 
 string githubToken;
-if (publishDocs)
-{
-    githubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN");
-    if (string.IsNullOrWhiteSpace(githubToken))
-    {
-        Console.Error.WriteLine("cannot publish docs without %GITHUB_TOKEN%");
-        Environment.Exit(1);
-    }
+if (publishDocs) {
+	githubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN");
+	if (string.IsNullOrWhiteSpace(githubToken)) {
+		Console.Error.WriteLine("cannot publish docs without %GITHUB_TOKEN%");
+		Environment.Exit(1);
+	}
 }
 
 string versionDLL;
 string versionNupkg;
 
 
-using (TextReader tr = new StreamReader("versions.txt"))
-{
-    versionDLL = tr.ReadLine().Split(":".ToCharArray())[1].Trim();
-    versionNupkg = tr.ReadLine().Split(":".ToCharArray())[1].Trim();
+using (TextReader tr = new StreamReader("versions.txt")) {
+	versionDLL = tr.ReadLine().Split(":".ToCharArray())[1].Trim();
+	versionNupkg = tr.ReadLine().Split(":".ToCharArray())[1].Trim();
 }
 
 Console.WriteLine("configuration: {0}", configuration);
@@ -74,15 +71,14 @@ Console.WriteLine("  - nupkg : {0}", versionNupkg);
 
 //////// PATCH SharedAssemblyInfo.cs
 string sharedAssemblyInfo = Path.Combine(
-    rootDir
-    , "src"
-    , "SharedAssemblyInfo.cs"
+	rootDir
+	, "src"
+	, "SharedAssemblyInfo.cs"
 );
 Console.WriteLine("Patching [{0}] to version [{1}]", sharedAssemblyInfo, versionDLL);
 string assemblyInfo;
-using (TextReader tr = new StreamReader(sharedAssemblyInfo, Encoding.UTF8))
-{
-    assemblyInfo = tr.ReadToEnd();
+using (TextReader tr = new StreamReader(sharedAssemblyInfo, new UTF8Encoding(false))) {
+	assemblyInfo = tr.ReadToEnd();
 }
 Console.WriteLine("old assemblyInfo:" + Environment.NewLine + assemblyInfo);
 Regex regex = new Regex("AssemblyVersion\\(\"([^)]*)");
@@ -91,25 +87,24 @@ regex = new Regex("AssemblyFileVersion\\(\"([^)]*)");
 assemblyInfo = regex.Replace(assemblyInfo, string.Format("AssemblyFileVersion(\"{0}\"", versionDLL));
 Console.WriteLine("new assemblyInfo:" + Environment.NewLine + assemblyInfo);
 
-using (TextWriter tw = new StreamWriter(sharedAssemblyInfo, false, Encoding.UTF8))
-{
-    tw.Write(assemblyInfo);
+using (TextWriter tw = new StreamWriter(sharedAssemblyInfo, false, Encoding.UTF8)) {
+	tw.Write(assemblyInfo);
 }
 //////// PATCH SharedAssemblyInfo.cs
 
 
 string buildCmd = string.Format(
-    "msbuild MapboxSdkCs.sln /p:Configuration={0}",
-    configuration
+	"msbuild MapboxSdkCs.sln /p:Configuration={0}",
+	configuration
 );
 Console.WriteLine("building [{0}]", buildCmd);
-if (!RunCommand(buildCmd, true))
-{
-    Console.Error.WriteLine("build failed");
-    Environment.Exit(1);
+if (!RunCommand(buildCmd, true)) {
+	Console.Error.WriteLine("build failed");
+	Environment.Exit(1);
 }
 
 
+//---------- nupkg
 string nugetCmd = string.Format("nuget pack -properties version={0}", versionNupkg);
 Console.WriteLine("creating nupkg: [{0}]", nugetCmd);
 Console.WriteLine("Skipping nuget pack! TODO: Build 'DebugNet' and 'DebugUWP' on one configuration!");
@@ -119,73 +114,75 @@ Console.WriteLine("Skipping nuget pack! TODO: Build 'DebugNet' and 'DebugUWP' on
 //     Environment.Exit(1);
 // }
 
+if (!publishNuget) {
+	Console.WriteLine("NOT publishing to nuget.org");
+} else {
+	Console.WriteLine("publishing to nuget.org");
+	string nugetCmd = string.Format("nuget push MapboxSdkCs.{0}.nupkg {1} -Source https://www.nuget.org/api/v2/package", versionNupkg, nugetApiKey);
+	if (!RunCommand(nugetCmd)) {
+		Console.Error.WriteLine("publishing to nuget.org failed");
+		Environment.Exit(1);
+	}
+}
 
 
-
-if (!publishNuget)
-{
-    Console.WriteLine("NOT publishing to nuget.org");
+//---------- documentation
+Console.WriteLine("downloading docfx ...");
+if (!RunCommand("powershell Invoke-WebRequest https://github.com/dotnet/docfx/releases/download/v2.14.1/docfx.zip -OutFile docfx.zip", true)) {
+	Console.Error.WriteLine("could not download docfx");
+	Environment.Exit(1);
 }
-else
-{
-    Console.WriteLine("publishing to nuget.org");
-    string nugetCmd = string.Format("nuget push MapboxSdkCs.{0}.nupkg {1} -Source https://www.nuget.org/api/v2/package", versionNupkg, nugetApiKey);
-    if (!RunCommand(nugetCmd))
-    {
-        Console.Error.WriteLine("publishing to nuget.org failed");
-        Environment.Exit(1);
-    }
+
+Console.WriteLine("extracting docfx ...");
+if (!RunCommand("7z x docfx.zip -aoa -o%CD%\\docfx | %windir%\\system32\\find \"ing archive\"", true)) {
+	Console.Error.WriteLine("could not extract docfx");
+	Environment.Exit(1);
 }
 
+Console.WriteLine("building docs ....");
 
-if (!publishDocs)
-{
-    Console.WriteLine("NOT publishing docs");
+if (!RunCommand(@"docfx src\Documentation\docfx.json", true)) {
+	Console.Error.WriteLine("generating docs failed");
+	Environment.Exit(1);
 }
-else
-{
-    Console.WriteLine("publishing dcos");
-    try
-    {
-        string originalCommit = Environment.GetEnvironmentVariable("APPVEYOR_REPO_COMMIT");
-        if (string.IsNullOrWhiteSpace(originalCommit))
-        {
-            originalCommit = "no SHA available";
-        }
-        else
-        {
-            originalCommit = "https://github.com/mapbox/mapbox-sdk-cs/commit/" + originalCommit;
-        }
-
-        string commitAuthor = Environment.GetEnvironmentVariable("APPVEYOR_REPO_COMMIT_AUTHOR");
-        if (string.IsNullOrWhiteSpace(commitAuthor))
-        {
-            commitAuthor = "no commit author available";
-        }
-
-        string docsDir = Path.Combine(rootDir, "src", "Documentation", "_site");
-        Console.WriteLine("docs directory: {0}", docsDir);
-        Environment.CurrentDirectory = docsDir;
-        List<string> cmds = new List<string>(new string[]{
+Console.WriteLine("docs successfully generated");
+
+if (!publishDocs) {
+	Console.WriteLine("NOT publishing docs");
+} else {
+	Console.WriteLine("publishing dcos");
+	try {
+		string originalCommit = Environment.GetEnvironmentVariable("APPVEYOR_REPO_COMMIT");
+		if (string.IsNullOrWhiteSpace(originalCommit)) {
+			originalCommit = "no SHA available";
+		} else {
+			originalCommit = "https://github.com/mapbox/mapbox-sdk-cs/commit/" + originalCommit;
+		}
+
+		string commitAuthor = Environment.GetEnvironmentVariable("APPVEYOR_REPO_COMMIT_AUTHOR");
+		if (string.IsNullOrWhiteSpace(commitAuthor)) {
+			commitAuthor = "no commit author available";
+		}
+
+		string docsDir = Path.Combine(rootDir, "src", "Documentation", "_site");
+		Console.WriteLine("docs directory: {0}", docsDir);
+		Environment.CurrentDirectory = docsDir;
+		List<string> cmds = new List<string>(new string[]{
             //"dir",
             "git init .",
-            "git add .",
-            string.Format("git commit -m \"pushed via [{0}] by [{1}]\"", originalCommit,commitAuthor),
-            string.Format("git remote add origin https://{0}@github.com/mapbox/mapbox-sdk-cs.git", githubToken),
-            "git checkout -b gh-pages",
-            "git push -f origin gh-pages"
-        });
-        foreach (var cmd in cmds)
-        {
-            if (!RunCommand(cmd))
-            {
-                Console.Error.WriteLine("publishing docs failed");
-                Environment.Exit(1);
-            }
-        }
-    }
-    finally
-    {
-        Environment.CurrentDirectory = rootDir;
-    }
+			"git add .",
+			string.Format("git commit -m \"pushed via [{0}] by [{1}]\"", originalCommit,commitAuthor),
+			string.Format("git remote add origin https://{0}@github.com/mapbox/mapbox-sdk-cs.git", githubToken),
+			"git checkout -b gh-pages",
+			"git push -f origin gh-pages"
+		});
+		foreach (var cmd in cmds) {
+			if (!RunCommand(cmd)) {
+				Console.Error.WriteLine("publishing docs failed");
+				Environment.Exit(1);
+			}
+		}
+	} finally {
+		Environment.CurrentDirectory = rootDir;
+	}
 }

scripts/omnisharp.json

@@ -0,0 +1,54 @@
+{
+    "FormattingOptions": {
+            //"NewLine": "\n",
+            "UseTabs": true,
+            "TabSize": 4,
+            "IndentationSize": 4,
+            "SpacingAfterMethodDeclarationName": false,
+            "SpaceWithinMethodDeclarationParenthesis": false,
+            "SpaceBetweenEmptyMethodDeclarationParentheses": false,
+            "SpaceAfterMethodCallName": false,
+            "SpaceWithinMethodCallParentheses": false,
+            "SpaceBetweenEmptyMethodCallParentheses": false,
+            "SpaceAfterControlFlowStatementKeyword": true,
+            "SpaceWithinExpressionParentheses": false,
+            "SpaceWithinCastParentheses": false,
+            "SpaceWithinOtherParentheses": false,
+            "SpaceAfterCast": false,
+            "SpacesIgnoreAroundVariableDeclaration": false,
+            "SpaceBeforeOpenSquareBracket": false,
+            "SpaceBetweenEmptySquareBrackets": false,
+            "SpaceWithinSquareBrackets": false,
+            "SpaceAfterColonInBaseTypeDeclaration": true,
+            "SpaceAfterComma": true,
+            "SpaceAfterDot": false,
+            "SpaceAfterSemicolonsInForStatement": true,
+            "SpaceBeforeColonInBaseTypeDeclaration": true,
+            "SpaceBeforeComma": false,
+            "SpaceBeforeDot": false,
+            "SpaceBeforeSemicolonsInForStatement": false,
+            "SpacingAroundBinaryOperator": "single",
+            "IndentBraces": false,
+            "IndentBlock": true,
+            "IndentSwitchSection": true,
+            "IndentSwitchCaseSection": true,
+            "LabelPositioning": "oneLess",
+            "WrappingPreserveSingleLine": true,
+            "WrappingKeepStatementsOnSingleLine": true,
+            "NewLinesForBracesInTypes": false,
+            "NewLinesForBracesInMethods": false,
+            "NewLinesForBracesInProperties": false,
+            "NewLinesForBracesInAccessors": false,
+            "NewLinesForBracesInAnonymousMethods": false,
+            "NewLinesForBracesInControlBlocks": false,
+            "NewLinesForBracesInAnonymousTypes": false,
+            "NewLinesForBracesInObjectCollectionArrayInitializers": false,
+            "NewLinesForBracesInLambdaExpressionBody": false,
+            "NewLineForElse": false,
+            "NewLineForCatch": false,
+            "NewLineForFinally": false,
+            "NewLineForMembersInObjectInit": false,
+            "NewLineForMembersInAnonymousTypes": false,
+            "NewLineForClausesInQuery": false
+    }
+}

src/Documentation/Documentation.csproj

@@ -53,20 +53,15 @@
     <None Include="articles\intro.md" />
     <None Include="articles\toc.md" />
     <None Include="articles\toc.yml" />
-    <None Include="packages.config" />
   </ItemGroup>
   <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
-  <Import Project="..\..\packages\docfx.msbuild.2.4.0\build\docfx.msbuild.targets" Condition="Exists('..\..\packages\docfx.msbuild.2.4.0\build\docfx.msbuild.targets')" />
-  <Target Name="EnsureNuGetPackageBuildImports" BeforeTargets="PrepareForBuild">
-    <PropertyGroup>
-      <ErrorText>This project references NuGet package(s) that are missing on this computer. Use NuGet Package Restore to download them.  For more information, see http://go.microsoft.com/fwlink/?LinkID=322105. The missing file is {0}.</ErrorText>
-    </PropertyGroup>
-    <Error Condition="!Exists('..\..\packages\docfx.msbuild.2.4.0\build\docfx.msbuild.targets')" Text="$([System.String]::Format('$(ErrorText)', '..\..\packages\docfx.msbuild.2.4.0\build\docfx.msbuild.targets'))" />
-  </Target>
   <PropertyGroup>
     <PreBuildEvent Condition="'$(OS)'=='Windows_NT'">copy /Y "$(ProjectDir)docfx.msbuild.targets" "$(SolutionDir)packages/docfx.msbuild.2.4.0/build/"</PreBuildEvent>
     <PreBuildEvent Condition="'$(OS)'!='Windows_NT'">cp -f "$(ProjectDir)docfx.msbuild.targets" "$(SolutionDir)packages/docfx.msbuild.2.4.0/build/"</PreBuildEvent>
   </PropertyGroup>
+  <PropertyGroup>
+    <PreBuildEvent />
+  </PropertyGroup>
   <!-- To modify your build process, add your task inside one of the targets below and uncomment it.
        Other similar extension points exist, see Microsoft.Common.targets.
   <Target Name="BeforeBuild">

src/Map/CanonicalTileId.cs

@@ -6,13 +6,14 @@
 
 namespace Mapbox.Map
 {
-    using System;
-    using Mapbox.Utils;
+	using System;
+	using Mapbox.Utils;
 
-    /// <summary>
-    ///     Canonical tile identifier in a slippy map.
-    /// </summary>
-    public struct CanonicalTileId
+	/// <summary>
+	/// Data type to store  <see href="https://en.wikipedia.org/wiki/Web_Mercator"> Web Mercator</see> tile scheme.
+	/// <see href="http://www.maptiler.org/google-maps-coordinates-tile-bounds-projection/"> See tile IDs in action. </see>
+	/// </summary>
+	public struct CanonicalTileId
 	{
 		/// <summary> The zoom level. </summary>
 		public readonly int Z;

src/Map/ClassicRasterTile.cs

@@ -9,6 +9,7 @@ namespace Mapbox.Map
 	/// <summary>
 	///    A raster tile from the Mapbox Map API, a encoded image representing a geographic
 	///    bounding box. Usually JPEG or PNG encoded.
+	/// See <see cref="T:Mapbox.Map.RasterTile"/> for usage.
 	/// </summary>
 	public class ClassicRasterTile : RasterTile
 	{