Move the documentation to Sphinx.

This allows us to use readthedocs.io to host the documentation, instead of building it as part of the release. The installer now points to readthedocs.io.
GPUOpen-Tools · Jun 8, 2017 · f3cfce2 · f3cfce2
1 parent fdf1cb6
commit f3cfce2
Show file tree

Hide file tree

Showing 20 changed files with 503 additions and 234 deletions.
diff --git a/.gitignore b/.gitignore
@@ -257,6 +257,7 @@ paket-files/
 *.sln.iml
 /docs/env
 /docs/output
+/docs/build
 /Installer/OCAT.Documentation.wxs
 *.wixpdb
 *.wixobj

diff --git a/COPYING b/COPYING
@@ -0,0 +1 @@
+See docs/license.rst for license information.
diff --git a/Installer/Installer.wixproj b/Installer/Installer.wixproj
@@ -22,15 +22,18 @@
     <IntermediateOutputPath>obj\$(Configuration)\</IntermediateOutputPath>
     <WixVariables>
     </WixVariables>
-    <DefineConstants>OCATInstaller.BinaryDir=$(SolutionDir)x64\$(Configuration);OCATInstaller.DocumentationDir=$(SolutionDir)docs\output</DefineConstants>
+    <DefineConstants>OCATInstaller.BinaryDir=$(SolutionDir)x64\$(Configuration)</DefineConstants>
     <SuppressValidation>False</SuppressValidation>
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="OCAT.Binaries.wxs" />
-    <Compile Include="OCAT.Documentation.wxs" />
     <Compile Include="Product.wxs" />
   </ItemGroup>
   <ItemGroup>
+    <WixExtension Include="WixUtilExtension">
+      <HintPath>$(WixExtDir)\WixUtilExtension.dll</HintPath>
+      <Name>WixUtilExtension</Name>
+    </WixExtension>
     <WixExtension Include="WixUIExtension">
       <HintPath>$(WixExtDir)\WixUIExtension.dll</HintPath>
       <Name>WixUIExtension</Name>
@@ -48,12 +51,11 @@
   </ItemGroup>
   <Import Project="$(WixTargetsPath)" />
   <PropertyGroup>
-    <PreBuildEvent>"%25WIX%25\bin\heat.exe" dir "$(SolutionDir)x64\$(ConfigurationName)" -var var.OCATInstaller.BinaryDir -dr INSTALLFOLDER -ag -cg OCATBinaries -scom -sreg -sfrag -srd -o "$(SolutionDir)Installer\OCAT.Binaries.wxs" -t "$(SolutionDir)Installer\filter.xslt"
-"%25WIX%25\bin\heat.exe" dir "$(SolutionDir)docs\output" -var var.OCATInstaller.DocumentationDir -dr DOCFOLDER -ag -cg OCATDocumentation -scom -sreg -sfrag -srd -o "$(SolutionDir)Installer\OCAT.Documentation.wxs"</PreBuildEvent>
+    <SuppressIces>ICE57</SuppressIces>
   </PropertyGroup>
   <PropertyGroup>
-    <SuppressIces>ICE57</SuppressIces>
-</PropertyGroup>
+    <PreBuildEvent>"%25WIX%25\bin\heat.exe" dir "$(SolutionDir)x64\$(ConfigurationName)" -var var.OCATInstaller.BinaryDir -dr INSTALLFOLDER -ag -cg OCATBinaries -scom -sreg -sfrag -srd -o "$(SolutionDir)Installer\OCAT.Binaries.wxs" -t "$(SolutionDir)Installer\filter.xslt"</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 Wix.targets.
@@ -62,4 +64,4 @@
 	<Target Name="AfterBuild">
 	</Target>
 	-->
-</Project>
+</Project>
diff --git a/Installer/Product.wxs b/Installer/Product.wxs
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
+<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi" xmlns:util="http://schemas.microsoft.com/wix/UtilExtension">
   <?define VersionNumber="!(bind.FileVersion.filB6514C65B44EDD23821C8C31D0EB462E)" ?>
   <Product Id="*" Name="Open Capture and Analytics Tool $(var.VersionNumber)" Language="1033" Version="$(var.VersionNumber)" Manufacturer="Advanced Micro Devices, Inc." UpgradeCode="5f8ad9ed-1fbe-4a7c-88f1-7d34675dd43b">
     <Package InstallerVersion="500" Compressed="yes" InstallScope="perMachine" InstallPrivileges="elevated" />
@@ -9,7 +9,6 @@
 
     <Feature Id="ProductFeature" Title="OCAT" Level="1">
       <ComponentGroupRef Id="OCATBinaries" />
-      <ComponentGroupRef Id="OCATDocumentation"/>
       <ComponentRef Id="ApplicationShortcut"/>
     </Feature>
   </Product>
@@ -32,10 +31,9 @@
                   Description="Open Capture and Analytics Tool"
                   Target="[INSTALLFOLDER]\OCAT.exe"
                   WorkingDirectory="INSTALLFOLDER"/>
-        <Shortcut Id="ApplicationStartMenuReadmeShortcut"
-                  Name="Readme"
-                  Description="Open Capture and Analytics Tool Readme"
-                  Target="[DOCFOLDER]\README.html"/>
+        <util:InternetShortcut Id="OnlineDocumentationShortcut"
+                        Name="OCAT Documentation"
+                               Target="http://ocat.readthedocs.io/en/v!(bind.property.ProductVersion.Major).!(bind.property.ProductVersion.Minor).!(bind.property.ProductVersion.Build)/"/>
         <RemoveFolder Id="ApplicationProgramsFolder" On="uninstall"/>
         <RegistryValue Root="HKMU" Key="Software\OCAT" Name="installed" Type="integer" Value="1" KeyPath="yes"/>
       </Component>

diff --git a/README.md b/README.md
@@ -4,27 +4,4 @@ The Open Capture and Analytics Tool (OCAT) provides an FPS overlay and performan
 
 ## Downloads
 
-For downloads, look into the releases section: https://github.com/GPUOpen-Tools/OCAT/releases
-
-
-## Setup
-
-This setup requires:
-- [Visual Studio 2015](https://www.visualstudio.com) or [Visual Studio 2017](https://www.visualstudio.com)
-- [Vulkan SDK](https://vulkan.lunarg.com/)
-- [Python 3.6](https://www.python.org/downloads/release/python-360/)
-- [.Net 4.5](https://www.microsoft.com/de-de/download/details.aspx?id=30653)
-
-Open Powershell in an appropriate directory and perform the following steps:
-
-```
-git clone https://github.com/GPUOpen-Tools/OCAT
-cd .\OCAT\
-.\pre-build.ps1
-.\build.ps1
-```
-
-The pre-build script pulls the MinHook submodule and downloads the redistributable files.
-It also builds the documentation. You can use the Visual Studio solution OCAT.sln afterwards.
-The build script performs the necessary steps to create the installer.
-After a successful build you can find the artifact in OCAT-Installer\bin\Release\OCAT.exe.
+For downloads, look into the releases section: https://github.com/GPUOpen-Tools/OCAT/releases
diff --git a/appveyor.yml b/appveyor.yml
@@ -30,13 +30,6 @@ notifications:
    incoming_webhook:
      secure: reZgP+MAKCYu9pDcH573P1Ecs9AZxzb+VqQVXNl10D/2RHG+SlxWI5LGN8HYP2AwoU+mfPb8TU0I8ZXaOvGKGu6ulW91E+qvPwlhZm3vIeI= 
 
-before_build:
- # Switch from python 2.7 to 3.6 as required for build.bat
- - ps: $Env:Path = $Env:Path -replace "C:\\Python27", "C:\Python36"
- - cd docs
- - call build.bat
- - cd ..
-
 build_script:
  # Choose the correct toolset depending on the Visual Studio in use.
  - ps: if( ($Env:APPVEYOR_BUILD_WORKER_IMAGE) -eq "Visual Studio 2015") { $Env:PLATFORM_TOOLSET="v140" }

diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/build.md b/docs/build.md
diff --git a/docs/build.bat → docs/build.ps1 b/docs/build.bat → docs/build.ps1
@@ -1,5 +1,5 @@
 python -m venv env
-call env/scripts/activate.bat
+.\env\scripts\activate.ps1
 python -m pip install --upgrade pip
 pip -q install -r requirements.txt
-python docgen.py
+.\make.bat html
diff --git a/docs/docgen.py b/docs/docgen.py
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+set SPHINXPROJ=OCAT
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1 @@
-jinja2
-commonmark
-pyyaml
+sphinx>=1.6
diff --git a/docs/source/build.rst b/docs/source/build.rst
@@ -0,0 +1,26 @@
+Building OCAT
+=============
+
+Prerequisites
+-------------
+
+- `Visual Studio 2017 <https://www.visualstudio.com>`_
+- `Vulkan SDK <https://vulkan.lunarg.com/>`_
+- `Python 3.6 <https://www.python.org/downloads/release/python-360/>`_
+- `.NET 4.5 <https://www.microsoft.com/en-us/download/details.aspx?id=30653>`_
+
+Build
+-----
+
+Open Powershell in an appropriate directory and perform the following steps:
+
+.. code-block:: PowerShell
+
+    git clone https://github.com/GPUOpen-Tools/OCAT
+    cd .\OCAT\
+    .\pre-build.ps1
+    .\build.ps1
+
+The pre-build script pulls the MinHook submodule and downloads the redistributable files.
+It also builds the documentation. You can use the Visual Studio solution ``OCAT.sln`` afterwards. The build script performs the necessary steps to create the installer.
+After a successful build you can find the artifact in ``OCAT-Installer\bin\Release\OCAT.exe``.
diff --git a/CHANGELOG.md → docs/source/changelog.rst b/CHANGELOG.md → docs/source/changelog.rst
@@ -1,21 +1,30 @@
-# OCAT Change Log
+Changelog
+=========
+
+1.0.1 - 2017-05-23
+------------------
+
+Added
+^^^^^
 
-## [1.0.1] - 2017-05-23
-### Added
 - Continuous integration via AppVeyor
 - Redesigned logging and debug system
 - Improved documentation on building OCAT from source
 - Proper marking of error codes
 - Changelogs for GitHub releases!
 
-### Changed
+Changed
+^^^^^^^
+
 - Blacklisted UplayWebCore and UbisoftGameLauncher
 - Blacklisted Firefox
 - Blacklisted RadeonSettings
 - Improved DXGI swapchain handling
 - Recording hotkey is now F12
 
-### Fixed
+Fixed
+^^^^^
+
 - Windows 10 Creators Update incompatibility via a PresentMon fix
 - Prey on Windows incompatibility
 - Doom and The Talos Principle (both Vulkan) incompatibility