CSharp/tips/CSharpでJavaDocみたいなドキュメントを作りたい - 豚吐露＠wiki

---

C#でJavaDocみたいなドキュメントを作りたい

---

Windows 7 Professional
Visual Studio 2013 Professional
.NetFramework 4.5

---

使用するツールの選定

『ドキュメンテーションコメント』『XMLコマンド』がキーワード。
ひな形は、『///』って入力するとVisual Studioが勝手に突っ込んでくれる。

試したのはSandcastleとDoxygen。
どちらも出力は可能だが、Office documentへの出力がSandcastleで不可能になってた。昔はできたみたい。

今回は諸事情により、Office document出力が可能なDoxygenを選択。

---

Sandcastleの導入と使い方

---

Doxygenの導入と使い方

---

ドキュメンテーションコメントからOffice document出力をしたい場合

Office document(Word)への出力はrtf形式を利用する。
※Excel形式の出力方法は、ちょっと見つかってねぇです。(´・ω・`)
※まぁ、XML出力はされるので、PowerShellとか.netとか使ってXMLファイルからごにょごにょすれば出力できるようになるっちゃぁなるんですが...

1.rtf形式の出力を有効化
2.出力されたrtfファイルのフィールドを更新
3.外部リンクになっている画像を埋め込みに変更

で対応できた。

---

Help File Formats

Sandcastle will produce output that can be used to create help files in various formats.
However, it cannot create the actual file that is the end result.
For that, help compilers or third-party build tools are required.
Below is a summary of the help file formats and the tools needed to produce them.

HTML Help 1

HTML Help 1 files are standalone help files with a .chm extension.
This is the oldest help file format and these files can be viewed on any system without any special viewers.
The Help 1 compiler is installed as part of the Microsoft HTML Help Workshop.

Microsoft Help 2

The Microsoft Help 2 format produces help files with a .HxS extension.
These are not standalone files.
In order to view them, they must be integrated into a help collection.
These are typically used to provide help for control libraries and tools and are integrated into the help collections used by Microsoft Visual Studio 2008 and earlier.
The Help 2 compiler does not appear to be available separately and must be installed as part of one of the SDKs for Visual Studio 2008 or earlier.

Microsoft Help Viewer

This is the latest help file format and produces help files with a .mshc extension.
These help files are typically used to provide help for control libraries and tools used with Visual Studio 2010 and later.
They are similar to Help 2 files in that they must be installed into a collection to be viewed but they do not require a compiler.
Instead, the help content is compressed into a ZIP-format archive file.
Third-party build tools for Sandcastle will provide the support necessary to create the help archive and its related configuration file.

Open XML

Open XML files are viewable in applications such as Microsoft Word and Open Office.
They have a .docx extension and are ZIP-format archive files.
Third-party build tools for Sandcastle will provide the support necessary to create the document archive file.
Since these are word processing documents, they are convertible to other file formats such as PDF using other third-party tools and applications.

There are certain requirements that need to be met in order to produce valid Open XML documents.
In addition, this file format is best suited to help content with 1,000 topics or less due to the number of pages that can be generated by much larger projects.
The larger the help content, the more unwieldy the resulting document can become.
See the Open XML Document File Format topic in the Sandcastle Help File Builder help file for details.

Websites

The topic files produced by Sandcastle are HTML files and can be used to create help content that is uploaded to a web server.
However, Sandcastle itself does not provide any support for creating a web-based table of content, index, or search functionality.
These features are left to the third-party build tools.
The following steps will check for the Help 1 and Help 2 compilers and give you instructions on downloading and installing them if necessary.
Click the Next button to continue.

HTML Help 1 Compiler

HTML Help 1 files are standalone help files with a .chm extension.
This is the oldest help file format and these files can be viewed on any system without any special viewers.

Help 1 Compiler Found

It has been determined that the HTML Help 1 compiler is installed on this system (Location: C:\Program Files (x86)\HTML Help Workshop).
No further action is required in this step.
Click the Next button to continue.

Microsoft Help 2 Compiler

The Microsoft Help 2 format produces help files with a .HxS extension. These are not standalone files. In order to view them, they must be integrated into a help collection. These are typically used to provide help for control libraries and tools and are integrated into the help collections used by Microsoft Visual Studio 2008 and earlier.

The Microsoft Help 2 compiler could not be found on this system. If you will be creating Help 2 files, you will need to follow the instructions below to download and install it using one of the listed SDKs. If you will not, you can safely skip this step. You can run this application again to install it later if needed.

Because the Help 2 compiler is not available separately, it must be installed as part of the Visual Studio SDK. This may require that you have the associated version of Microsoft Visual Studio installed as well. It is only available in SDKs for Visual Studio 2008 and earlier.

You only need to install one of the following SDKs to obtain the Help 2 compiler components.

The SDKs for Visual Studio 2005 and 2008 both contain an outdated version of Sandcastle. This can cause problems after installing Sandcastle as the environment variable that it uses to find its components may point to the wrong location causing build errors. If you install one of the SDKs, it is highly recommended that you reboot before continuing with the Sandcastle tools installation so that the issue can be detected and fixed.

If you have Visual Studio 2010 or later

Help 2 files are not used by Visual Studio 2010 or later and their related SDKs do not contain the Help 2 compiler.

If you have Visual Studio 2008

NOTE: You must install version 1.0 of the Visual Studio 2008 SDK. Version 1.1 does not contain the Help 2 compiler components.

・Click this link to go to the download page: Visual Studio 2008 SDK Version 1.0
・Once the page opens, click the Download button.
・When prompted, click the Run button to download and immediately run the installer.
・When it has finished, come back to this application and click the Search Again button below to ensure that the Help 2 compiler can be found.
・It is highly recommended that you reboot before installing the remainder of the Sandcastle tools so that a potential issue with the SDK can be detected and fixed prior to installing Sandcastle. See the note above for more information.

If you have Visual Studio 2005

・Click this link to go to the download page: Visual Studio 2005 SDK Version 4.0
・Once the page opens, click the Download button.
・When prompted, click the Run button to download and immediately run the installer.
・When it has finished, come back to this application and click the Search Again button below to ensure that the Help 2 compiler can be found.
・It is highly recommended that you reboot before installing the remainder of the Sandcastle tools so that a potential issue with the SDK can be detected and fixed prior to installing Sandcastle. See the note above for more information.

If you have Visual Studio 2003

・Click this link to go to the download page: Visual Studio .NET Help Integration Kit 2003
・Once the page opens, click the Download button.
・When prompted, click the Run button to download and immediately run the installer.
・When it has finished, come back to this application and click the Search Again button below to ensure that the Help 2 compiler can be found.

The Microsoft Help 2 compiler does not appear to be installed.
Microsoft Help 2 files cannot be produced without it.
If you will not be creating them, you can safely skip this step.
If you will, you should download and install it before proceeding.

Do you want to proceed without?

Sandcastle Help File Builder and Tools

The Sandcastle Help File Builder (SHFB) was created to provide project managment features, add the missing NDoc-like features that are used most often, and provide graphical and command line based tools to build a help file in an automated fashion using the Sandcastle Tools. The most recent version of both can always be found at the Sandcastle Help File Builder project on CodePlex.

This will install the core tools and build engine and the standalone GUI project management system. A Visual Studio package is also available that will allow you to create, manage, and build help file projects from within Visual Studio. It is installed separately. The core tools and build engine are required for it to work correctly and must be installed first.

See the topics in the Getting Started section of the Sandcastle Help File Builder help file for information on additional tools that you may find useful and how to create your first project.

The Sandcastle Help File Builder could not be found on this system.  Please  click the Install SHFB button below.  A separate installer will be launched to perform the installation.  Once it has completed, return to this application to continue installing the remainder of the tools.  You may need to reboot when done so that changes to the system environment variables take effect.

http://shfb.codeplex.com/

---

更新日： 2014年11月19日 (水) 11時49分57秒