사용자 문서 관리에 Maven 사용

Question

우리는 Java 서버 스타일 응용 프로그램을 작성하는 데 Maven을 사용하고 있습니다. 이는 고객이 필요로하는 기능을 갖춘 최종 제품 (기본적으로 .jar)을 생성하기 위해 서로 연결될 수있는 여러 개의 모듈로 구성됩니다 (하나의 Maven "reactor"에 있음). 모든 내부는 JavaDoc과 모두를 사용하여 문서화되어 있지만, 이는 고객에게 실행 방법을 알려주는 것이 아닙니다. 현재 우리는 최종 사용자 문서로 사용되는 OpenOffice 문서를 보유하고 있습니다.

각 모듈의 문서가 모듈의 소스와 함께 유지 관리되고 최종 문서가 필요한 모듈 문서 섹션을 참조하고, 친숙한 서문을 추가하고, 관련 문서를 추가 할 수있는 메이븐 빌드 프로세스에이 문서를 통합하고 싶습니다. , 가능한 경우 JavaDocs를 참조 할 수 있습니다. 궁극적으로, 문서는 PDF로 출력되어야합니다.

Maven 플러그인에 대한 경험이 있습니까? DocBook은 올바른 도구입니까? 아마 라텍스? 아니면 완전히 다른 무엇인가? "오픈 오피스와 일부 텍스트 블록을 고수하는"소리도 대답이 될 수 있습니다.

Answer 1

나는 으로 아직 Maven site documentation generation을 보지 않았다고 가정합니다. 꽤 견고하며 오픈 오피스 (OpenOffice) 문서의 컨텐트와 JavaDoc 세대를 통합하여 포함시킬 수 있습니다.

사이트 설명서는 PDF로 출력되지 않지만 많은 기능이 내장 된 정적 HTML 웹 사이트로 출력됩니다. Maven 프로파일을 사용하면 Maven이 다음을 포함하는 내부 사용을위한 하나의 사이트를 생성하도록 구성 할 수 있습니다. Checkstykle 및 PMD와 같은 수표에 대한 확실한 테스트 결과 및 기타 보고서. 다른 프로파일에서, 클라이언트가 관심을 두지 않을 수도있는 내부 보고서를 포함하지 않는 클라이언트로의 분 h에 필요한.서만 생성하도록 구성 할 수 있습니다.

한 참고하지만, 메이븐 3의 대부분은 메이븐 2와 호환 동안 사이트의 문서 생성의 대부분은 메이븐 3. 체크 아웃에 대한보고 변경이 링크 염두 메이븐 (3)에 대한 변화 :

• Converting maven-site-plugin for Maven 3

Answer 2

그리고 충분히 높은 품질을 생산하지 않는 외부 문서와 사이트 플러그인, 당신은 HTML 및 PDF 출력을 생성하기 위해 메이븐과의 DocBook을 사용할 수있는 경우

Site Generation Compatibility

. 실제로 Sonatype은 Maven : The Complete Reference, Nexus book, M2Eclipse book ... 등 모든 책에서이를 수행하며 오픈 소스이므로 모든 기능이 어떻게 작동하는지보고 설정을 복사하고 필요에 맞게 수정할 수 있습니다. 도크 북을 사용하는 이점은 툴링이 꽤 좋으며 (예 : xmlmind) 색인, toc 등으로 인쇄 품질 서적을 생산한다는 것입니다.

아, 그리고 당신이 그것을 언급 한 이후이 Maven을위한 LaTeX의 플러그인도하지만 난 그것과 경험이 없다 (하지만 내 Maven을 사용하기 전에 LaTeX의와 꽤 ...)

Answer 3

또 다른 솔루션은 메이븐입니다 docbkx DocBook을 PDF로 변환하기위한 플러그인. HTML 등

변환 된 DocBook to HTML을 Maven 프로젝트 사이트에 추가하는 방법에 대한 설명을 읽으십시오. DocBook 콘텐츠가 Maven 생성 사이트에도 표시되도록하려면이 설명을 읽으십시오.

흥미 롭 관련 질문 :

• What is the recommended tool chain for formatting XML DocBook?.

Answer 4

각 모듈에는 docbook 형식으로 작성된 자체 참조 매뉴얼이있는 다중 모듈 프로젝트가 있습니다. 그리고 나는 문서를 다시 사용하기 위해 다른 것들도 포함하는 일반적인 참고 매뉴얼을 가지고있다. mvn 사이트를 실행하면 프로젝트는 모든 참조 설명서가 포함 된 HTML 및 PDF 파일을 생성하며 maven 사이트에 깔끔하게 통합됩니다. 이 경우 docbkx 플러그인을 사용합니다. 나는 그것이 정말로 흔들린다 고 생각한다. 여기에 플러그인 구성입니다 :

  <plugin> 
      <groupId>com.agilejava.docbkx</groupId> 
      <artifactId>docbkx-maven-plugin</artifactId> 
      <executions> 
       <execution> 
        <id>docbook-HTML</id> 
        <phase>pre-site</phase> 
        <goals> 
         <goal>generate-html</goal> 
        </goals> 
        <!-- HTML configuration --> 
        <configuration> 
         <generateToc>false</generateToc> 
         <targetDirectory>${project.build.directory}/site</targetDirectory> 
         <htmlCustomization>${basedir}/src/site/docbkx-config/docbook-html.xsl</htmlCustomization> 
         <htmlStylesheet>./css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet> 
         <chunkedOutput>false</chunkedOutput> 
        </configuration> 
       </execution> 
       <execution> 
        <id>docbook-PDF</id> 
        <phase>pre-site</phase> 
        <goals> 
         <goal>generate-pdf</goal> 
        </goals> 
        <!-- PDF configuration --> 
        <configuration> 
         <generateToc>true</generateToc> 
         <paperType>A4</paperType> 
         <imgSrcPath>file:///${basedir}/src/site/resources/</imgSrcPath> 
         <calloutGraphicsPath>file:///${basedir}/src/site/resources/images/callouts/</calloutGraphicsPath> 
         <calloutGraphicsExtension>.svg</calloutGraphicsExtension> 
         <calloutGraphicsNumberLimit>30</calloutGraphicsNumberLimit> 
         <calloutIconSize>6</calloutIconSize> 
         <shadeVerbatim>true</shadeVerbatim> 
         <targetDirectory>${project.build.directory}</targetDirectory> 
         <foCustomization>${basedir}/src/site/docbkx-config/docbook-fo.xsl</foCustomization> 
         <!-- <bodyFontFamily>Kaffeesatz</bodyFontFamily> 
         <monospaceFontFamily>LiberationMono</monospaceFontFamily> 
         --> 
         <fonts> 
          <font> 
           <name>Kaffeesatz</name> 
           <style>normal</style> 
           <weight>normal</weight> 
           <embedFile>${basedir}/src/fonts/YanoneKaffeesatz-Regular.ttf</embedFile> 
           <metricsFile>${basedir}/target/fonts/YanoneKaffeesatz-Regular-metrics.xml</metricsFile> 
          </font> 
          <font> 
           <name>LiberationMono</name> 
           <style>normal</style> 
           <weight>normal</weight> 
           <embedFile>${basedir}/src/fonts/LiberationMono-Regular.ttf</embedFile> 
           <metricsFile>${basedir}/target/fonts/LiberationMono-Regular-metrics.xml</metricsFile> 
          </font> 
          <font> 
           <name>VeraMono</name> 
           <style>normal</style> 
           <weight>normal</weight> 
           <embedFile>${basedir}/src/fonts/VeraMono.ttf</embedFile> 
           <metricsFile>${basedir}/target/fonts/VeraMono-metrics.xml</metricsFile> 
          </font> 
         </fonts> 
        </configuration> 
       </execution> 
      </executions> 
      <!-- Shared configuration --> 
      <configuration> 
       <sourceDirectory>${basedir}/src/site/docbkx</sourceDirectory> 
       <includes>*.xml</includes> 
       <xincludeSupported>true</xincludeSupported> 
       <generatedSourceDirectory>${project.build.directory}/site</generatedSourceDirectory> 
       <highlightSource>1</highlightSource> 
       <calloutGraphics>true</calloutGraphics> 
       <!-- DEFAULT HTML CONFIG --> 
       <targetDirectory>${project.build.directory}/site</targetDirectory> 
       <htmlCustomization>src/site/docbook-config/docbook-html.xsl</htmlCustomization> 
       <htmlStylesheet>css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet> 
       <!-- // DEFAULT HTML CONFIG --> 
      </configuration> 
     </plugin> 

당신은 내 프로젝트 사이트 here을 확인할 수 있습니다 당신은 심지어 당신의 컴퓨터에 소스를 다운로드하고 모든 일이 설정되는 방법을 확인할 수 있습니다. 질문이 있으시면 언제든지 연락주십시오.

는 마침내 저장소를 설정하고 메이븐 사이트 세대 해본 적이

건배를 카를로스