Website ouput: Merge documentation from different sources

Topics: Developer Forum
May 2, 2013 at 9:56 PM
I apologize in advance if this question has been answered in the documentation and/or faq. I searched, but could not find the answer to what what I am looking for.

Here is what I am trying to do: Create a website like docs.company.com that has a startup page with links to documentation created by Sandcastle (website output). Here is the issue:

The html pages in the html folder (with <guid>.htm files) refer to other pages (links to items within the documenation - classes, interfaces etc) with the relative URL /html, For example:
<a href="/html/d98c1dd4-008f-04b2-e980-0998ecf8427e.htm" target="">Empty</a><br /><b>Schema:</b><a href="/html/329dc1c3-8006-c1e7-ff2b-2a70a0437531.htm" target="">Some Item</a>
So, If I am reading this correctly, the links will not work if I place the output in folders like this:

doc1
index.htm
html\guid1.htm
html\guid2.htm

doc2
index.htm
html\guid3.htm
html\guid4.htm

If I click a link in say, doc1\html\guid1.htm that has a reference to html\guid2.htm, it will go to \html\guid2.html and such a file does not exist, because it is in doc1\html.

In other words my question is: How do I merge the documentation from multiple sources (for website output) into one usable documentation webstie? Is this possible?

Thanks in advance!
Coordinator
May 3, 2013 at 3:02 AM
You can't merge the website output of two separate projects. There are no provisions for merging the website TOCs or guaranteeing that any of the links in the pages will work properly since each project is unaware of the other. You'd have to create a single SHFB project combining the documentation sources of both projects and build a single website from it.

Eric
May 7, 2013 at 4:42 PM
I also need to merge separate but related API docs. Is there a way to combine those documentation sources and specify where each API reference appears?

ConceptualA
ReferenceA
ConceptualB
ConceptualC
ReferenceC

..or would I have to do this?

Conceptual
A, B, C
Reference
A, C


Coordinator
May 7, 2013 at 8:54 PM
There are no provisions for merging content in website and Help 1 output. I don't recall the specifics for Help 2 but the most you can do there I think is host it in one or more given collections. MS Help Viewer is more flexible as you can use the project's TOC Parent Topic ID property to host the content under a specific topic GUID even if it's not in the current project (i.e. another project's topic or even a standard topic in Microsoft's help content). As such, it is possible to simulate merging of content in MS Help Viewer by that method. One project would most likely serve as the primary content or a shell containing root topics to which the others would be attached. The only thing to be careful of is that you don't duplicate any MAML topic GUIDs or API member IDs across all projects as that will cause problems.

Eric
May 8, 2013 at 7:22 PM
Eric,

Is it possible to use a Post Transform component to change the references to all <a href="/html/guid.htm" /> to <a href="../html/guid.htm" />? If so, can you point me in the right direction?

Thanks.
Coordinator
May 8, 2013 at 8:29 PM
A build component is probably not necessary. Reference links are generated by ResolveReferenceLinksComponent2 and ResolveConceptualLinksComponent. By default, they contain no path, just the GUID plus a ".htm" extension. ResolveReferenceLinksComponent2 supports an href-format attribute that defines the local link format. ResolveConceptualLinksComponent supports a url attribute on the target elements that defines the link format.

SHFB does not use nor does it expose a way to alter those attributes. In order to change them, you could write a plug-in that alters the configuration files to add the appropriate attributes to the necessary configuration elements. I haven't looked to closely at the required format nor have I documented them yet so you'd have to poke around in the build component source code to figure out the required value format. There's a topic in the SHFB help file on writing plug-ins so that would be the place to look for into on writing the actual plug-in.

Eric