Blog Rupra a Engina

Generování dokumentace VS2005 přes NDoc

Tak jsem po dlouhé době pohledal, či se nepohl projekt NDoc pro VS2005 a FW2.0 a ejhle. Po trochu boji to funguje. Takže jak na to?

 Na stránkách sourceForge se jako klasicky dá najít několik projektů (binaries nebo src). Binaries bohužel obsahují kompilační chyby. My se zaměříme na naše překompilované sources s některými sekcemi zdrojového kódu, které budeme muset opravit. Takže:

 1) Potřebujeme src od projektu NDoc 2005 BetaRelease, které nalezneme na

http://sourceforge.net/project/showfiles.php?group_id=163095&package_id=184303&release_id=411019

odkazem NDoc2005BetaSrc.zip.

2) Rozbalíme, otevřeme ve studiu a je třeba provést změnu v souboru .\Msdn\MsdnHtmlUtilitiesV20.cs záměnou obsahu metody InitializeNamespace() za tento kód:

        /// <summary>
        /// Initialize namespace dictionary
        /// </summary>
        public static void InitializeNamespaces(Project project)
        {
            // If we don't have namespaces list yet, go through each referenced assembly,
            // load the assembly, get the types, then cache the namespaces for all public types.
            if (namespaces.Count == 0)
            {
                foreach (AssemblySlashDoc doc in project.AssemblySlashDocs)
                {
                    //
                    string strDllFullPath = doc.Assembly.Path;
                    string strDllPath = strDllFullPath.Substring(
                        0, strDllFullPath.LastIndexOf(@"\") + 1);
                    //

                    Assembly theAssembly = Assembly.LoadFrom(doc.Assembly);
                    AssemblyName[] assemblies = theAssembly.GetReferencedAssemblies();

                    foreach (AssemblyName an in assemblies)
                    {
                        //Assembly assembly = Assembly.LoadWithPartialName(an.Name);
                        Assembly assembly = null;
                        try
                        {
                            assembly = Assembly.LoadFrom(strDllPath + an.Name + ".dll");
                        }

                        catch (Exception ex)
                        {
                            try
                            {
                                assembly = Assembly.Load(an.FullName);
                            }

                            catch (Exception ex1)
                            {
                                continue;
                            }
                        }

                        if (assembly == null)
                        {
                            throw new System.IO.FileNotFoundException(
                                String.Concat(
                                    "Unable to locate the referenced Assembly ", an.Name));
                        }

                        Type[] assemblyTypes = assembly.GetTypes();

                        foreach (Type type in assemblyTypes)
                        {
                            if (type.IsPublic)
                            {
                                namespaces[type.Namespace] = 
                                    type.Namespace.Replace('.', '_') + '_';
                                namespaces[type.Namespace.Replace(".", "")] = 
                                    type.Namespace.Replace('.', '_') + '_';
                            }
                        }
                    }
                }
            }
        }

        (zdroj : http://geekswithblogs.net/SudheersBlog/archive/2006/07/24/86146.aspx)

3) Dalším problém je, že zdroje (xslt, css, aj. soubory) jsou definovány relativně vzhledem ke kompilovatelné verzi.  Proto funkčnost samotných zkompilových souborů je třeba udělat 2 věci (ve zdrojových souborech upravit string zdroje dat, a do složky s výstupem přidat složky se šablonami.

Funkční verzi jsem upravil pouze pro výstup MSDN (pro mě jediný potřebný - zatím):

3a) v projektu MSDN do souboru StyleSheetCollection.cs přidat definici

#define RELEASE_RESOURCES

a následně v metodě LoadStyleSheets nahradit celou sekci #if NO_RESOURCES ... #endif za například toto:

#if RELEASE_RESOURCES
         string resourceBase = "file://" + Path.GetFullPath(
            Path.Combine(System.Windows.Forms.Application.StartupPath, @"Msdn\xslt"));
#else
#if NO_RESOURCES
	string resourceBase = "file://" + Path.GetFullPath(
            Path.Combine(
                System.Windows.Forms.Application.StartupPath, 
                @"..\..\..\Documenter\Msdn\xslt") );
#else
         string resourceBase = "NDoc.Documenter.Msdn.xslt";
#endif
#endif

3b) Ve výstupní složce vytvoříme novou složku nazvanou "MSDN" a vykopírujeme do ní z projektu MSDN podsložky CSS, Images, OnlineFiles, OnlineTemplates a xslt.

4) Zkompilujeme, spustíme a projekt by měl fungovat.

ENG

 Zdroje:

http://www.wwwcoder.com/main/parentid/263/site/6246/68/default.aspx

http://geekswithblogs.net/SudheersBlog/archive/2006/07/24/86146.aspx

http://sourceforge.net/tracker/index.php?func=detail&aid=1479548&group_id=163095&atid=826379

http://forums.microsoft.com/msdn/showpost.aspx?postid=111392&siteid=1&sb=0&d=1&at=7&ft=11&tf=0&pageid=1

PS:

Při rozcházení NDoc05 se nejčastěji objevují 2 základní chyby:

• Could not find a part of the path <nějaká cesta>\Msdn\xslt\namespace.xslt'. - je způsobenou pevnou cestou určenou při kompilaci balíku a vyskytuje se pouze u binárních verzí. U verzí vycházejíccíh ze zdrojových souborů (náš případ) se při překompilování cesta nahradí správnou a chyba nenastane;
• Falied to load Assembly <název>- je zase chyba, která se vyskytuje při nenahrazení metody InitializeNamespaces() uvedené v bodě 2.