Restructured for single table of contents (docs/readme.md)

Removed numbering on file naming and separated into separate sub-directories for getting-started, using, and contributing.
olnistratov · Dec 31, 2015 · 9ccb224 · 9ccb224
1 parent 4d1a15a
commit 9ccb224
Show file tree

Hide file tree

Showing 51 changed files with 385 additions and 436 deletions.
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
-| Squirrel.Windows |
+| README.md |
 |:---|
 
-![](docs/images/Squirrel-Logo.png)
+![](docs/artwork/Squirrel-Logo.png)
 
 # Squirrel: It's like ClickOnce but Works™
 
@@ -19,47 +19,20 @@ Windows apps should be as fast and as easy to install and update as apps like Go
 * **Installing** is Wizard-Free™, with no UAC dialogs, does not require reboot, and is .NET Framework friendly.
 * **Updating** is in the background, doesn't interrupt the user, and does not require a reboot.
 
-Refer to our full list of goals for [integrating, packaging, distributing, installing, and updating](docs/0-What-Do-We-Want.md).
+Refer to our full list of goals for [integrating, packaging, distributing, installing, and updating](docs/goals.md).
 
-## 1 Getting Started
+## Documentation
 
-Section 1, [Getting Started](docs/1-Getting-Started.md), will step through the integration of Squirrel.Windows for a basic c# application. The steps for using Squirrel.Windows with your application include the following:
+See the documentation [Table of Contents](docs/readme.md) for an overview of the available documentation for Squirrel.Windows. It includes a [Getting Started Guide](docs/GettingStarted/0-index.md) as well as additional topics related to using Squirrel in your applications. 
 
-* [1.1 Integrating](docs/1.1-Integrating.md) - integrating Squirrel update into your application.
-* [1.2 Packaging](docs/1.2-Packaging.md) - packaging application files and preparing them for release.
-* [1.3 Distributing](docs/1.3-Distributing.md) - providing install and update files for users.
-* [1.4 Installing](docs/1.4-Installing.md) - process of initial installation of your application.
-* [1.5 Updating](docs/1.5-Updating.md) - process of updating an existing install.
 
-## 2 Advanced Usage
-
-Section [2 Advanced Usage](docs/2-Advanced-Usage.md), explores specific advanced topics for using Squirrel, including the following:
-
-
-* [2.1 More Integrating](docs/2.1-More-Integrating.md) - details on integrating Squirrel in MyApp along with advanced topics (e.g., [Debugging](docs/2.1-Integrating-Debugging.md), [Custom Squirrel Events](docs/2.1-Integrating-Custom-Events.md)).
-* [2.2 More Packaging](docs/2.2-More-Packaging.md) - packaging meta data details and advanced topics (e.g., [Automating Packaging](docs/2.2.2-Packing-Automate-Nuspec.md), [Delta Packages](docs/2.2-Packaging-Delta-Packages.md), [Application Signing](docs/2.2-Packaging-Releasify-Application-Signing.md)).
-* [2.3 More Distributing](docs/2.3-More-Distributing.md) - additional distribution options (e.g., [Microsoft IIS](docs/2.3-Distributing-IIS.md), [GitHub](docs/2.3-Distributing-GitHub.md), [Amazon S3](docs/2.3-Distributing-Amazon-S3.md)).
-* [2.4 More Installing](docs/2.4-More-Installing.md) - detailed install steps and advanced topics (e.g., [Machine-wide Installs](docs/2.4-Machine-wide-Installs.md), [Loading GIF](docs/2.4-Loading-Gif.md)).
-* [2.5 More Updating](docs/2.5-More-Updating.md) - detailed update steps.
-
-
-## 3 Contributing
-
-Why not give back and help make Squirrel even better by [contributing](docs/3-Contributing.md) to the project.
-
-## 4 FAQ
-
-Have a question? Review the [Frequently Asked Questions (FAQ)](docs/4-FAQ.md) document. 
-
-## 5 Copyright and Usage
+## License and Usage
 
 See [COPYING](COPYING) for details on copyright and usage of the Squirrel.Windows software.
 
 
 
----
-|Next: [1 Getting Started](docs/1-Getting-Started.md)|
-|:---|
+
 
 
 

diff --git a/docs/1-Getting-Started.md b/docs/1-Getting-Started.md
diff --git a/docs/1.3-Distributing.md b/docs/1.3-Distributing.md
diff --git a/docs/2-Advanced-Usage.md b/docs/2-Advanced-Usage.md
diff --git a/docs/2.3-More-Distributing.md b/docs/2.3-More-Distributing.md
diff --git a/docs/3-Contributing.md b/docs/3-Contributing.md
diff --git a/docs/X-Doc-Template.md b/docs/X-Doc-Template.md
diff --git a/docs/images/Squirrel-Logo.png → docs/artwork/Squirrel-Logo.png b/docs/images/Squirrel-Logo.png → docs/artwork/Squirrel-Logo.png
diff --git a/docs/images/Squirrel-Logo.svg → docs/artwork/Squirrel-Logo.svg b/docs/images/Squirrel-Logo.svg → docs/artwork/Squirrel-Logo.svg
diff --git a/docs/contributing/building-squirrel.md b/docs/contributing/building-squirrel.md
@@ -0,0 +1,21 @@
+| [docs](..)  / [contributing](.) / building-squirrel.md
+|:---|
+
+# Building Squirrel
+
+Squirrel.Windows is a fairly typical C# / C++ project, the only special part is making sure to clone submodules via the command shown below.
+
+For the Impatient:
+
+```sh
+git clone https://github.com/squirrel/squirrel.windows
+git submodule update --init --recursive       ## THIS IS THE PART YOU PROBABLY FORGOT
+.\.NuGet\NuGet.exe restore
+msbuild /p:Configuration=Release
+```
+
+**Tip:** You can compile the Squirrel.Windows solution with Visual Studio version 2013 and above (including community edition).
+
+---
+| Return: [Table of Contents](../readme.md) |
+|----|
diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md
@@ -0,0 +1,21 @@
+| [docs](..)  / [contributing](.) / contributing.md
+|:---|
+
+# Contributing
+
+Why not give back and help make Squirrel even better? Here is an overview of ways you can become more involved.
+
+* **Join the Squirrel Slack Room** - email [paul@paulbetts.org](mailto:paul@paulbetts.org) with the email address you'd like to receive an invite.
+* **Contribute Documentation** - improve the documentation or provide additional code examples to benefit others.
+* **Subscribe to Issues on GitHub** - have some experience using Squirrel? Help answer questions under issues or post a Pull Request fixing a bug.
+* **Contribute Code** -  have a great feature that you feel is a good fit for Squirrel? Send a Pull Request.
+
+
+## See Also
+
+* [Building Squirrel](building-squirrel.md) - steps to build squirrel for the impatient.
+* [VS Solution Overview](vs-solution-overview.md) - overview of the various projects in the Squirrel.Windows Visual Studio solution.
+
+---
+| Return: [Table of Contents](../readme.md) |
+|----|
diff --git a/docs/3-Contributing-VS-Solution-Overview.md → docs/contributing/vs-solution-overview.md b/docs/3-Contributing-VS-Solution-Overview.md → docs/contributing/vs-solution-overview.md
@@ -1,10 +1,9 @@
-| [Squirrel.Windows](../README.md) / [3\. Contributing](3-Contributing.md) |
+| [docs](..)  / [contributing](.) / vs-solution-overview.md
 |:---|
 
-# 3 Contributing: Visual Studio Solution Overview
+# Visual Studio Solution Overview
 
-An overview of the various projects in the Squirrel.Windows Visual Studio solution and how they relate to different 
-aspects of the update process.
+An overview of the various projects in the Squirrel.Windows Visual Studio solution and how they relate to different aspects of the update process.
 
 
 | Project / Assembly Name | Libraries (NuGet) | Libraries (NuGet) | Releases Directory (releasify output) | MyApp (install location) |
@@ -25,6 +24,6 @@ aspects of the update process.
 **Note**: Note that the Squirrel.exe application found in the tools directory of the Squirrel.Windows NuGet package is actually a renamed version of the Update.exe application (see Squirrel.Windows\src\Squirrel.nuspec) 
 
 ---
-|Return: [3\. Contributing](3-Contributing.md)|
-|:---|
+| Return: [Table of Contents](../readme.md) |
+|----|
 
diff --git a/docs/4-FAQ.md → docs/faq.md b/docs/4-FAQ.md → docs/faq.md
@@ -1,14 +1,14 @@
-| [Squirrel.Windows](../README.md) |
+| [docs](.) / faq.md |
 |:---|
 
-# 4 FAQ
+# Frequently Asked Questions (FAQ)
 
 Frequently Asked Questions for Squirrel.Windows, organized by area below.
 
 ## Integrating
 
 1. **Can Squirrel.Windows be used on applications that aren't made with .Net?**  
-   Yes, you can package a non-c# application in the same manner as described in the Getting Started guide. For additional customization, see section 2.1 on integrating [custom squirrel events for non-c# apps](2.1-Integrating-Custom-Events-Non-CS.md).  
+   Yes, you can package a non-c# application in the same manner as described in the Getting Started guide. For additional customization, see [custom squirrel events for non-c# apps](using/custom-squirrel-events-non-CS.md).  
 1. **How do I migrate a ClickOnce app to Squirrel?**  
    You may want to look into the [ClickOnceToSquirrelMigrator](https://github.com/flagbug/ClickOnceToSquirrelMigrator) migration helper.
 
@@ -22,14 +22,14 @@ Frequently Asked Questions for Squirrel.Windows, organized by area below.
 ## Distributing
 
 1. **Can I distribute update files on IIS?**  
-Yes you can, see [2.3 Distributing: Microsoft IIS](2.3-Distributing-IIS.md) for details.
+Yes you can, see [Microsoft IIS](using/microsoft-iis.md) for details.
 
 ## Installing
 
 1. **The Initial Install via `Setup.exe` is failing. How do I learn what is going wrong?**  
    Check `%LocalAppData%\SquirrelTemp\SquirrelSetup.log` for logs related to the initial install.
 1. **Installer application doesn't do anything. The animation flashes but the application never starts.**  
-   The app is likely crashing on the first run (see [2.1 Integrating: Debugging](2.1-Integrating-Debugging.md) for details).
+   The app is likely crashing on the first run (see [Debugging Installs](using/debugging-installs.md) for details).
 2. **The Installer seems to be blocked in Enterprise environments. How can confirm this?**  
   Squirrel may be prevented from installing if Group Policy disallows the running of executables from `%LocalAppData%`. In this case, the "show log" button on the "installation failed" dialog will fail because `Update.exe` can not run to create a log file.  
 
@@ -46,11 +46,12 @@ This program is blocked by group policy. For more information, contact your syst
 ## Updating
 
 1. **How do I determine what is going wrong with the UpdateManager in MyApp?**  
-   You can setup your `\bin` directory so you can execute MyApp in the Visual Studio debugger and simply step through the update process as well as catch exceptions and log the results (see [2.1 Integrating: Debugging](2.1-Integrating-Debugging.md) for details)
+   You can setup your `\bin` directory so you can execute MyApp in the Visual Studio debugger and simply step through the update process as well as catch exceptions and log the results (see [Debugging Updates](using/debugging-updates.md) for details)
 2. **I've Distributed a Broken Copy of Update.exe. How can I fix this?**  
    Sometimes, you might ship a broken copy of `Update.exe` that succeeds the initial install, but doesn't do what you want for some reason. To fix this, you can force an update of the `Update.exe` by including a copy of `Squirrel.exe` in your app update package. If Squirrel sees this, it will copy in this latest version to the local app installation.
-
+3. **How can you replace DLLs while they're loaded? Impossible!**  
+   You can't. So, how can you do it? The basic trick that ClickOnce uses is, you have a folder of EXEs and DLLs, and an Application Shortcut. When ClickOnce goes to update its stuff, it builds a completely *new* folder of binaries, then the last thing it does is rewrite the app shortcut to point to the new folder. See []
 
 ---
-| Return: [Squirrel.Windows](../README.md) |
+| Return: [Table of Contents](readme.md) |
 |:---|
diff --git a/docs/getting-started/0-overview.md b/docs/getting-started/0-overview.md
@@ -0,0 +1,34 @@
+| [docs](..) / [getting-started](.) / 0-overview.md|
+|:---|
+
+# Getting Started Guide
+
+Getting Started will walk you through the integration of Squirrel.Windows for a basic c# Windows Forms application named MyApp.
+
+## MyApp
+
+MyApp simply displays the assembly location and application version on a simple form.
+
+![](images/1-MyApp.png)
+
+For simplicity, any unneeded references and files have been removed from the solution.
+
+![](images/1-MyApp-Solution.png)
+
+If you wish to follow along, you can [download](Example/MyApp.zip) a zip file of the MyApp solution.
+
+## Overview
+This guide will go over the following steps to demonstrate using Squirrel.Windows to distribute and update MyApp.
+
+1. [Integrating](1-integrating.md) - integrating Squirrel `UpdateManager` into your application.
+1. [Packaging](2-packaging.md) - packaging application files and preparing them for release.
+1. [Distributing](3-distributing.md) - providing install and update files for users.
+1. [Installing](4-installing.md) - process of initial installation of your application.
+1. [Updating](5-updating.md) - process of updating an existing install.
+
+---
+| Next: [1. Integrating](1-integrating.md)|
+|:---|
+
+
+