I don't want to add all DocProjects to my Solution

Topics: General Questions
Nov 6, 2008 at 3:50 PM
Edited Nov 6, 2008 at 4:02 PM
Hello,

we need to generate a lot of different documentations out of the same sourcecode solution. Each of them has different look and different API filters. If I understood it right the DocProject approach to this would be to add an extra DocProject project to the source code solution.

But this way our actual sourcecode solution gets cluttered with tons of DocProject projects. Also developers that do not have DocProject installed would not be able to correctly load the solution.
Is there a way to maintan the source code project and the DocProject projects independently? Or is ther another "best practise" that handles these to issues?
Coordinator
Nov 6, 2008 at 5:10 PM
Hi,

> Each of them has different look and different API filters.  If I understood it right the DocProject approach to this would be to add an extra DocProject project to the source code solution

That's one option.  Another option for varying API filters would be to use a single DocProject and then customize the build process so that it swaps out different Settings\toc.xml and Help\Presentation\Style\Configuration\MRefBuilder.config files depending upon the current solution configuration or the value of some MSBuild properties.

See this thread for more info:
http://social.msdn.microsoft.com/Forums/en-US/devdocs/thread/81eef4fb-ba6e-415e-95fc-273ba3b39a53

For simple changes to the "look" you can swap out other files as well such as the CSS files and icons; however, if you need to use completely different Sandcastle presentation styles then yes, you'll need to create separate projects.

> Is there a way to maintan the source code project and the DocProject projects independently

If you don't want to add DocProjects to your solution you can create another solution that contains all of your projects including your DocProjects and use this solution as your build target.  This works especially well if you're using a build server since it's common to use a custom MSBuild script anyway.

- Dave

Nov 6, 2008 at 8:05 PM
> If you don't want to add DocProjects to your solution you can create another solution that contains all of your projects including your DocProjects and use this solution as your build target.  This works especially well if you're using a build server since it's common to use a custom MSBuild script anyway.

This seems like a good solution, but (this might be more of a Team Server question, sorry if this is too off topic):

I would like to put the solution with DocProjects into team Server sourcecontrol because there will be several people editing it. The actual sourcecode solution is on that Team Server as well. So for the DocProject Solution I would have to do "Add existing project" wich result in two soultions referencing the same project. Do you think Team Server will be able to understand and keep this cross reference alive? So that if a developer that already has got the sourcecode solution locally and now gets the new DocProject solution from Team Server it will not try to put another copy of the referenced projects onto the local devmachine? Because it would be rather tedious to copy the sourcode solution output upon each build. Any tips? Will it work right away?
Coordinator
Nov 7, 2008 at 12:31 AM
Hi,

If you set up the directory structure in Team Server and the working directory structure on your dev computers appropriately then I don't see why there would be any problems.

I think the binding information for the DocProjects will be constant regardless of which solution they are added to, so as long as the root working folder is above (i.e., contains) all of the solutions then you should be fine.

Here's the directory structure that I like to use (or at least something similar) for my projects under source control to enable situations like yours:

  • Root
    • Development (for branching)
      • ... usually similar to the Main folder structure ...
    • Main (active development; branch from here and merge back later when necessary)
      • Source
        • Project1
          • Project1.csproj
        • Project2
          • Project2.csproj
      • Tests
        • UI, unit, performance, etc.
      • Docs
        • DocProjects and DocSites
      • Deployment
        • Various MSBuild scripts, Web Deployment projects, Setup and Deployment projects, etc.
      • Build
        • Various MSBuild scripts for building (not necessarily required if you're using Team Build, although that's not my area of expertise)
      • Solution1.sln (for example, references all projects in Source and Tests)
      • Solution2.sln (for example, references all projects in Source and Docs)
I bind my local working directory to the project's root, which is typically the name of the company or project.  The solutions bind to projects that are below them in the directory structure (i.e., projects are added to a new blank solution via Add > Existing Project...) so you only need one copy of each project.  This structure should work well on everyone's development machine.  What's nice about solution files is that you can execute them directly from MSBuild or via another MSBuild script, such as something that Team Build might generate/use.

This source control layout was taken straight from the Team System source control guidance on the TFSGuide project here and here.  And don't forget to check out that project's home page for more good stuff.

- Dave
Nov 7, 2008 at 8:33 AM
Yes, you are right, it looks like it just works right out of the box.