Sphinx is an open-source tool for creating documentation. Written originally for the documentation of Python projects it also supports C/C++ with plans in the pipeline for support of other languages. Right now, my interest in Sphinx is that it is the tool used by readthedocs.org where I am planning to host the documentation for BrightstarDB.
BrightstarDB is a .NET application written in C# and I'm quite happy with the output of Sandcastle for the API documentation. However the developer and user docs were all originally created using the (commercial) Help & Manual application - which is a great documentation tool in its own right but would require contributors to the project to purchase a license in order to update or extend the docs.
Getting a local version of Sphinx running is the first step in evaluating if this approach is going to be feasible and as I'm developing on Windows 8, getting it running under Windows is my priority. So my goal here is to document how to install all you need to run Sphinx on Windows - with the qualifier that I'm doing this on Windows 8. YMMV on other Windows OSes.
I came across this problem when trying to create a strongly-typed MVC4 view using the List scaffolding template in Visual Studio 2010. When trying to add the view, an error is generated that reports:
c:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\ItemTemplates\CSharp\Web\MVC 4\CodeTemplates\AddView\CSHTML\List.tt(206,35):
error CS0104: Compiling transformation: 'ColumnAttribute' is an ambiguous reference between
'System.ComponentModel.DataAnnotations.ColumnAttribute' and 'System.Data.Linq.Mapping.ColumnAttribute'
The fix for this is to locate that .TT file (
c:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\ItemTemplates\CSharp\Web\MVC 4\CodeTemplates\AddView\CSHTML\List.tt) and on line 206 change
var column = attribute as ColumnAttribute;
var column = attribute as System.Data.Linq.Mapping.ColumnAttribute;
Strangely, this error does not occur in a VS2012 installation so it must have got fixed at some point but even after reinstalling MVC4 into VS2010 the error still came up.
Hopefully this post will help someone else find the fix !
Edit: The same problem seems to also affect the
Create.tt template (on line 122), the
Delete.tt template (line 174),
Details template (line 179) and the
Edit template (line 229) - the same fix works in all cases.