LinDol's 실험실

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
====== C# API 문서 생성 ======

===== XML 문서 파일 생성 =====

프로젝트 속성-> 빌드 옵션으로 이동합니다.

하단부의 출력 옵션 지정에서 XML 문서 파일(X) 옵션을 체크 합니다.
출력 경로는 및 출력 파일의 이름은 기본 설정 그대로 사용하도록 합니다. ( 별도 위치 및 이름으로 지정 가능 )

{{::output_setting_in_build_tab_from_project_properties.jpg|}}

옵션을 활성화 한 후 프로젝트를 저장합니다.

프로젝트를 다시 빌드하게 되면 앞서서 지정한 출력 위치에 XML 문서 파일이 생성 됩니다.

{{::outputs_in_debug_directory.jpg|}} {{:summary_of_c_sharp_xml_document.jpg?300|}}

이를 가지고 우리는 MSDN 형식의 .chm(도움말 파일) 및 웹 페이지를 생성할 것입니다.

===== Sandcastle 및 Helper Tool 설치 =====

이제 XML 문서를 이용해 API 문서를 생성하기 위한 툴을 설치하도록 합니다.

이용할 도구는 Sandcastle 이지만 우리는 [[http://shfb.codeplex.com/|Sandcastle Help File Builder]] 을 이용할 것입니다.

==== 다운로드 ====

Sandcastle Help File Builder [[http://shfb.codeplex.com/releases/view/81770|다운로드]]

다운로드 링크로 이동해 **Sandcastle Help File Builder Installer를** 다운로드한 후 압축을 해제하고 설치를 진행합니다.

(현재 : SHFB v1.9.4.0 with Visual Studio Package 가 최신-2012년 9월 14일 기준 )

설치 실행 파일의 이름은 SandcastleInstaller 입니다.

==== 설치 ====

처음 설치를 시작하면 환영 메시지가 표시됩니다. **Next를** 클릭합니다.

{{::sandcastle_guided_installation_step1.jpg?300|}}

Microsoft .Net Framework가 설치되었는지 확인하는 화면입니다. **Next를** 클릭합니다.

{{::sandcastle_guided_installation_step2.jpg?300|}}

Help File Format에 대한 내용을 표시합니다. **Next를** 클릭합니다.

{{::sandcastle_guided_installation_step3.jpg?300|}}

HTML Help 1 Compiler가 설치되어 있는지 확인합니다. **Next를** 클릭합니다. ( VisualStudio 설치시 이미 설치됨 )

{{::sandcastle_guided_installation_step4.jpg?300|}}

Microsoft Help 2 Compiler 에 대한 내용입니다. **Next를** 클릭합니다. ( Visual Studio 2010 이상은 해당 없음 )

Help2 내용을 제외하고 진행하도록 대화상자가 표시되면 **예 를** 선택하고 계속 진행합니다.

{{::sandcastle_guided_installation_step5.jpg?300|}}

Sandcastle Tools에 대한 내용을 표시하는 화면입니다.
Sandcastle가 설치되어 있지 않은 경우 하단에 **Install Sandcastle 버튼이** 표시됩니다.

이 버튼을 누르고 Sandcastle Tool을 설치합니다.

{{::sandcastle_guided_installation_step6.jpg?300|}}

Sandcastle Tool 설치가 진행되는 화면 ( 라이센스 동의 후 기본 옵션 그대로 계속 "Next" 버튼을 누르시면 됩니다. )

{{::install_sandcastle_tool_in_sandcastle_guided_installation_step7.jpg?300|}}

Copy VS2010 Style Branding package에 대한 내용을 표시하는 화면입니다.

하단의 **Copy Branding Package 버튼을** 클릭해 패키지를 설치합니다.

패키지 설치를 마친 후 **Next 버튼을** 클릭합니다.

{{::sandcastle_guided_installation_step8.jpg?300|}}

MAML Schema IntellSense for Visual Studio 에 대한 화면 입니다. ( **Schemas 를 설치할 필요는 없음** )

**Next버튼을** 클릭합니다.

{{::sandcastle_guided_installation_step9.jpg?300|}}

Sandcastle Help File Builder에 대한 정보를 표시하는 화면입니다.

화면 하단의 **Install SHFB 버튼을** 클릭해 Builder 설치를 진행합니다.

설치를 마치면 **Next 버튼을** 클릭합니다.

{{::sandcastle_guided_installation_step10.jpg?300|}}

{{::install_builder_tool_in_sandcastle_guided_installation_step11.jpg?300|}}

Sandcastle Help File Builder Visual Studio Package에 대한 내용을 표시합니다. ( **설치할 필요 없음.** )

**Next를** 클릭합니다.

{{::sandcastle_guided_installation_step12.jpg?300|}}

설치가 완료 되었습니다.

**Close 버튼을** 클릭합니다.

{{::sandcastle_guided_installation_step13.jpg?300|}}

===== Sandcastle 문서 프로젝트 생성 =====

**시작->모든 프로그램-> Sandcastile Help File Builder -> Sandcastle Help File Builder를** 이용해 프로그램을 실행 시킵니다.

다음은 프로그램의 실행 화면입니다.

{{::sandcastle_help_file_builder_1.jpg?300|}}

메뉴에서 File-> New Project를 선택합니다.

선택을 마치면 **Save New Help Project As** 다이얼로그가 표시되며 프로젝트가 생성될 디렉토리로 이동한 후 프로젝트 파일의 이름을 입력하도록 합니다.

{{::sandcastle_help_file_builder_step_2.jpg?300|}}

다음은 새로운 api 문서화 프로젝트가 생성된 화면입니다.

{{::sandcastle_help_file_builder_step_3.jpg?300|}}

===== 문서 프로젝트 설정 =====

이제 문서를 생성할 c# project를 지정하도록 합니다.

우측 영역의 **Project Explorer의 Documentation Sources 를 선택한** 후 마우스 우측 버튼을 클릭합니다.

그리고 **Add Documentation Source 를** 선택합니다.

{{::project_explorer_in_sandcastle_help_file_builder_step_4.jpg?300|}}

메뉴를 선택하면 Select the documentation sources(s) 다이얼로그가 표시되며 여기서 문서를 생성할 프로젝트의 출력인 .exe 파일을 선택해 주도록 합니다. ( 또는 .dll 파일 )

{{::sandcastle_help_file_builder_step_4.jpg?300|}}

출력 파일을 선택하면 다음과 같이 앞서 생성했었던 XML 문서 파일과 함께 출력 파일이 Documeneation Source로 등록 됩니다.

{{::sandcastle_help_file_builder_step_5.jpg?300|}}

다음은 생성할 문서의 형태를 지정하고 추가적인 옵션을 설정하도록 합니다.

Build 탭의 HtmlFileFormat 속성에서 출력할 문서의 형태를 지정할 수 있습니다.

도움말 파일 형태로 문서를 만들고자 할 경우 HtmlHelp1 및 HtmlHelp2를 선택하고 웹 페이지 형태로 만들고자 할 경우 WebSite를 선택합니다.

WebSite를 선택하도록 합니다.

다음은 출력할 문서의 형태를 WebSite로 변경하는 화면입니다.

{{::propeties_in_sandcastle_helpfile_builder_1.jpg?300|}}

다음은 생성할 문서의 언어 및 제목 등의 기본적인 옵션을 지정하도록 합니다. 

Help File 탭에서는 이러한 옵션을 지정할 수 있으며 여기서는 생성할 언어를 한국어로 지정할 것입니다.

다음은 Help File 탭의 Language 속성을 한국어로 지정하는 화면입니다.

{{::propeties_in_sandcastle_helpfile_builder_2.jpg?300|}}

이제 api 문서가 생성될 위치를 지정하도록 합니다. 문서가 생성될 위치는 OutputPath로 지정할 수 있습니다.

다음은 Paths 탭의 OutputPath 속성을 지정하는 화면입니다.
여기서는 ( C:\Users\LinDol\Documents\api document\ 로 지정하였음, 바탕화면에 하면 잘 안되더라는.. )

{{::propeties_in_sandcastle_helpfile_builder_3.jpg?300|}}

다음은 문서로 생성할 대상의( 클래스 및 기타 ) 범위를 지정하는 옵션입니다.

기본적인 옵션 그대로 사용할 경우 접근 범위가 **public 로 지정된 클래스들을** 대상으로 하게 됩니다.

다음은 가시성을 지정하는 화면 입니다.

{{::propeties_in_sandcastle_helpfile_builder_4.jpg?300|}}

모든 것이 완료 되었습니다.

이제 메뉴에서 **Documentation -> Build Project를** 선택합니다.

Build를 선택하면 다음 화면과 같이 문서를 생성하게 됩니다.

{{::sandcastle_helpfile_builder_5.jpg?300|}}

===== API 문서 =====

다음은 OutputPath로 지정한 위치에 웹 페이지 형식으로 생성된 MSDN 스타일의 API 문서 입니다. ^.^
문서 파일의 이름은 index.html 입니다.

{{::api_webpage_generated_sandcastle.jpg|}}