docs: antora setup

Author: alandefreitas

.github/workflows/ci.yml

@@ -102,6 +102,53 @@ jobs:
       run:
         shell: bash
 
+    name: Publish docs
+    timeout-minutes: 30
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+
+      - name: Install Antora
+        working-directory: docs
+        run: |
+          npm install
+
+      - name: Generate Site
+        working-directory: docs
+        run: |
+          master_antora_exists=$(curl --silent --fail --head https://github.com/cppalliance/mrdox/blob/master/docs/antora.yml >/dev/null && echo "true" || echo "false")
+          develop_antora_exists=$(curl --silent --fail --head https://github.com/cppalliance/mrdox/blob/develop/docs/antora.yml >/dev/null && echo "true" || echo "false")
+          if [ "$master_antora_exists" == "true" ] && [ "$develop_antora_exists" == "true" ]; then
+              # Antora is set up in both master and develop: render complete playbook
+              npx antora antora-playbook.yml
+          else
+              # Antora is not set up in master and develop yet: render local playbook while integration is not complete
+              # The local playbook is used for local development and for the documentation included in the release
+              npx antora local-antora-playbook.yml
+          fi
+
+      - name: Publish to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build/site
+          force_orphan: true
+
+  releases:
+    needs: build
+    if: ${{ github.event_name == 'push' && (contains(fromJSON('["master", "develop"]'), github.ref_name) || startsWith(github.ref, 'refs/tags/')) }}
+    defaults:
+      run:
+        shell: bash
+
     name: Create Release Packages
     timeout-minutes: 120
     runs-on: ubuntu-22.04

.gitignore

@@ -8,3 +8,5 @@
 /test-files/py
 /test-files/**/*.adoc
 /test-files/**/*.bad.xml
+docs/node_modules
+docs/build

CMakeLists.txt

@@ -36,6 +36,7 @@ include(GNUInstallDirs)
 
 option(MRDOX_BUILD_TESTS "Build tests" ${BUILD_TESTING})
 option(MRDOX_BUILD_SHARED "Link shared" OFF)
+option(MRDOX_BUILD_DOCS "Configure install target" OFF)
 option(MRDOX_INSTALL "Configure install target" ON)
 option(MRDOX_PACKAGE "Build install package" ON)
 
@@ -218,7 +219,7 @@ source_group(TREE ${PROJECT_SOURCE_DIR}/source PREFIX "source" FILES ${SOURCES})
 #
 #-------------------------------------------------
 
-if (BUILD_TESTING)
+if (MRDOX_BUILD_TESTS)
     file(GLOB_RECURSE TEST_SOURCES CONFIGURE_DEPENDS source/*.cpp source/*.hpp)
     enable_testing()
     add_test(NAME mrdox-test COMMAND mrdox --action test
@@ -260,6 +261,37 @@ if (BUILD_TESTING)
     endif()
 endif()
 
+
+#-------------------------------------------------
+#
+# Docs
+#
+#-------------------------------------------------
+
+if (MRDOX_BUILD_DOCS)
+    find_program(NPM_EXECUTABLE npm)
+    find_program(NPX_EXECUTABLE npx)
+
+    if(NPM_EXECUTABLE AND NPX_EXECUTABLE)
+        message(STATUS "NPM found: ${NPM_EXECUTABLE}")
+        message(STATUS "NPX found: ${NPX_EXECUTABLE}")
+
+        set(DOCS_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/docs)
+        set(DOCS_BUILD_DIR ${DOCS_SOURCE_DIR}/build/site)
+        set(DOCS_INSTALL_DIR ${CMAKE_INSTALL_PREFIX}/doc/mrdox/html)
+
+        # Add custom target for generating documentation
+        add_custom_target(generate_docs
+                COMMAND ${NPM_EXECUTABLE} install
+                COMMAND ${NPX_EXECUTABLE} antora local-antora-playbook.yml
+                WORKING_DIRECTORY ${DOCS_SOURCE_DIR}
+                COMMENT "Generating MrDox documentation"
+                )
+    else()
+        message(WARNING "NPM or NPX not found. Unable to generate documentation.")
+    endif()
+endif ()
+
 #-------------------------------------------------
 #
 # Install
@@ -285,6 +317,14 @@ if (MRDOX_INSTALL)
             DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
             FILES_MATCHING PATTERN "*.[hic]pp")
 
+    # Set installation rules for generated documentation
+    if (MRDOX_BUILD_DOCS)
+        install(DIRECTORY ${DOCS_BUILD_DIR}
+                DESTINATION ${DOCS_INSTALL_DIR}
+                COMPONENT documentation
+                )
+    endif()
+
     # Set variable where the cmake config is
     # https://cliutils.gitlab.io/modern-cmake/chapters/install/installing.html
     set(CONFIG_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/mrdox)

NOTES.adoc

@@ -0,0 +1,3 @@
+:linkcss:
+:stylesdir: https://cppalliance.github.io/mrdox/_/stylesheets
+:stylesheet: site.css

docs/.asciidoctorconfig

@@ -0,0 +1,29 @@
+# npm install
+# npx antora --fetch antora-playbook.yml
+site:
+  title: MrDox
+  url: https://cppalliance.github.io/mrdox/
+  start_page: mrdox::index.adoc
+  robots: allow
+  keys:
+    repo_url: 'https://github.com/cppalliance/mrdox'
+
+content:
+  branches: [ master, develop ]
+  tags: [ v* ]
+  edit_url: 'https://github.com/cppalliance/mrdox/edit/{refname}/{path}'
+  sources:
+    - url: https://github.com/cppalliance/mrdox.git
+      start_path: docs
+      edit_url: 'https://github.com/cppalliance/mrdox/edit/{refname}/{path}'
+
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+
+antora:
+  extensions:
+    - require: '@antora/lunr-extension' # https://gitlab.com/antora/antora-lunr-extension
+      index_latest_only: true
+

docs/antora-playbook.yml

@@ -0,0 +1,10 @@
+name: mrdox
+title: MrDox
+version: true
+start_page: index.adoc
+asciidoc:
+  attributes:
+    source-language: asciidoc@
+    table-caption: false
+nav:
+  - modules/ROOT/nav.adoc

docs/antora.yml

@@ -0,0 +1,26 @@
+# npm install
+# npx antora --fetch local-antora-playbook.yml
+site:
+  title: MrDox
+  url: https://cppalliance.github.io/mrdox/
+  start_page: mrdox::index.adoc
+  robots: allow
+  keys:
+    repo_url: 'https://github.com/cppalliance/mrdox'
+
+content:
+  sources:
+    - url: ..
+      start_path: docs
+      edit_url: 'https://github.com/cppalliance/mrdox/edit/{refname}/{path}'
+
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+
+antora:
+  extensions:
+    - require: '@antora/lunr-extension' # https://gitlab.com/antora/antora-lunr-extension
+      index_latest_only: true
+

docs/design-notes.adoc

@@ -0,0 +1,6 @@
+* xref:index.adoc[]
+* xref:install.adoc[]
+* xref:design-notes.adoc[]
+* xref:usage.adoc[]
+* xref:contribute.adoc[]
+* xref:license.adoc[]

docs/local-antora-playbook.yml

@@ -0,0 +1,5 @@
+= Contribute
+
+
+
+

docs/modules/ROOT/images/MrDoxBanner.png

@@ -0,0 +1,25 @@
+= Design Notes
+
+== AST Traversal
+
+During the AST traversal stage, the complete AST (generated by the clang frontend) is walked beginning with the root `TranslationUnitDecl` node.
+It is during this stage that USRs (universal symbol references) are generated and hashed with SHA1 to form the 160 bit `SymbolID` for an entity.
+With the exception of built-in types, *all* entities referenced in the corpus will be traversed and be assigned a `SymbolID`; including those from the standard library.
+This is necessary to generate the full interface for user-defined types.
+
+== Bitcode
+
+AST traversal is performed in parallel on a per-translation-unit basis.
+To maximize the size of the code base MrDox is capable of processing, `Info` types generated during traversal are serialized to a compressed bitcode representation.
+Once AST traversal is complete for all translation units, the bitcode is deserialized back into `Info` types, and then merged to form the corpus.
+The merging step is necessary as there may be multiple identical definitions of the same entity (e.g. for class types, templates, inline functions, etc), as well as functions declared in one translation unit & defined in another.
+
+== The Corpus
+
+After AST traversal and `Info` merging, the result is stored as a map of `Info`s indexed by their respective `SymbolID`s. Documentation generators may traverse this structure by calling `Corpus::traverse` with a `Corpus::Visitor` derived visitor and the `SymbolID` of the entity to visit (e.g. the global namespace).
+
+== Namespaces
+
+Namespaces do not have a source location.
+This is because there can be many namespaces.
+We probably don't want to store any javadocs for namespaces either.

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,38 @@
+= MrDox
+Alan Freitas <alandefreitas@gmail.com>
+:description: MrDox: A Clang/LLVM tool for building reference documentation from C++ code and javadoc comments.
+:sectanchors:
+:url-repo: https://github.com/cppalliance/mrdox
+:page-tags: mrdox
+:navtitle: Home
+
+image::MrDoxBanner.png[]
+
+Welcome to MrDox, the ultimate solution for generating comprehensive reference documentation from your {cpp} codebase and javadoc comments. MrDox harnesses the power of Clang/LLVM, offering a seamless and efficient way to document your {cpp} projects.
+
+With MrDox, you can effortlessly extract valuable insights and produce detailed documentation for your {cpp} code. By leveraging the rich semantic knowledge provided by Clang/LLVM, MrDox accurately captures the nuances of your codebase, including class hierarchies, functions, and their respective parameters and return types. This ensures that your documentation is not only informative but also up-to-date, eliminating the need for manual documentation maintenance.
+
+The integration of javadoc-style comments takes your documentation to the next level. With MrDox, you can easily embed human-readable explanations, usage examples, and additional contextual information directly within your code. These comments serve as a valuable resource for both developers and consumers of your code, promoting clarity and understanding.
+
+MrDox seamlessly fits into your development workflow, with the freedom to customize the output format to suit your project requirements. MrDox offers versatile options for output formats, including XML and Asciidoc. In addition to the provided output formats, MrDox empowers users to bring their own creativity and customization to the documentation generation process. With support for handlebars templates, you can create and apply your own unique templates to the generated documentation. This allows you to customize the styling, layout, and overall presentation of your documentation, making it truly personalized and aligned with your project's branding.
+
+MrDox empowers you to produce high-quality documentation that benefits both developers and users. Explore the power of MrDox today and experience the ease of building comprehensive reference documentation for your {cpp} projects. Say goodbye to tedious manual documentation and embrace the efficiency and accuracy of MrDox.
+
+== Comparison
+
+=== Doxygen:
+
+* tries to work for many languages
+* use the inferior libclang API
+* old program with lots of technical debt
+* not written by me
+
+=== MrDox:
+
+* narrow and deep focus on {cpp} only
+* uses clang's unstable libtooling API:
+** Understands ALL C++: if clang can compile it, MrDox knows about it
+** This includes up to {cpp}20 and even experimental things in {cpp}23
+* brand-new program with no technical debt
+* written by me
+