feat: adding script for generating Mardown docs (also adding macOS Docker support)

.devcontainer/ci/Dockerfile

@@ -24,6 +24,15 @@ ARG USER
 # Local Environment Variable(s)
 ENV LC_ALL="C.UTF-8"
 
+# Install adduser package for user creation utilities
+RUN ["dash", "-c", "\
+    apt-get update --quiet \
+ && apt-get install --assume-yes --no-install-recommends --quiet \
+     adduser \
+ && apt-get clean \
+ && rm -rf /var/lib/apt/lists/* \
+"]
+
 # Create Non-Root User
 RUN ["dash", "-c", "\
     addgroup \
@@ -70,6 +79,7 @@ RUN ["dash", "-c", "\
  && pip install --break-system-packages \
      breathe \
      sphinx-rtd-theme \
+     sphinx-markdown-builder \
  && apt-get clean \
  && apt-get purge \
  && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* \

.devcontainer/ci/devcontainer.json

@@ -6,9 +6,13 @@
     // Sets the run context to one level up instead of the .devcontainer folder.
     "context": "${localWorkspaceFolder}",
 
-    // Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
-    "image": "ghcr.io/blues/note_c_ci:latest",
-    // "dockerFile": "Dockerfile",
+    // Use pre-built image (faster, but only works on amd64 or with Docker Desktop's platform emulation):
+    // "image": "ghcr.io/blues/note_c_ci:latest",
+    // Use local Dockerfile (works on all platforms, required for Apple Silicon):
+    "dockerFile": "Dockerfile",
+
+    // Force amd64 platform for Apple Silicon compatibility
+    "runArgs": ["--platform=linux/amd64"],
 
     // Set *default* container specific settings.json values on container create.
     "settings": {},

README.md

@@ -16,6 +16,8 @@ it as a git subtree.
 
 The API documentation for this library can be found [here][note-c API docs].
 
+The documentation can also be built locally in either HTML or Markdown format. See [Building Markdown Documentation](docs/BUILDING_MARKDOWN.md) for details on generating Markdown documentation.
+
 ## Logging Control
 
 `note-c` provides a comprehensive and flexible logging functionality.

docs/BUILDING_MARKDOWN.md

@@ -0,0 +1,114 @@
+# Building Markdown Documentation
+
+The note-c documentation can now be generated in Markdown format in addition to HTML. This is useful for reusing the documentation in other contexts.
+
+## Prerequisites
+
+### Local Build
+
+To build the documentation locally, you need the following installed:
+
+1. **Doxygen** (version 1.9.8 or later)
+2. **Sphinx** and required Python packages
+
+Install Python dependencies:
+```bash
+pip install -r docs/requirements.txt
+```
+
+Or install individually:
+```bash
+pip install sphinx breathe sphinx-rtd-theme sphinxcontrib-jquery sphinx-markdown-builder
+```
+
+### Docker Build
+
+Alternatively, use the provided Docker container which includes all dependencies:
+
+```bash
+docker build .devcontainer/ci/ --tag note_c_docs
+```
+
+## Building Documentation
+
+### HTML Documentation (Original)
+
+To build the HTML documentation:
+
+```bash
+# Using the build script
+./scripts/build_docs.sh
+
+# Or using CMake directly
+cmake -B build/ -DNOTE_C_BUILD_DOCS:BOOL=ON
+cmake --build build/ -- docs
+```
+
+The HTML output will be in `build/docs/index.html`
+
+### Markdown Documentation (New)
+
+To build the Markdown documentation:
+
+```bash
+# Using the build script
+./scripts/build_docs_markdown.sh
+
+# Or using CMake directly
+cmake -B build/ -DNOTE_C_BUILD_DOCS:BOOL=ON
+cmake --build build/ -- docs-markdown
+```
+
+The Markdown output will be in `build/docs/markdown/`
+
+### Using Docker
+
+To build documentation using Docker:
+
+```bash
+# Build the Docker image (if not already built)
+docker build .devcontainer/ci/ --tag note_c_docs
+
+# Run the build inside Docker
+docker run --rm --volume $(pwd):/note-c/ --workdir /note-c/ note_c_docs bash -c "./scripts/build_docs_markdown.sh"
+```
+
+## Output Structure
+
+The Markdown documentation maintains the same structure as the HTML documentation:
+
+- `index.md` - Main documentation index
+- `api_reference.md` - API reference documentation
+- `getting_started.md` - Getting started guide
+- `calling_the_notecard_api.md` - API usage guide
+- `library_initialization.md` - Library initialization guide
+- `ports.md` - Porting guide
+
+The API documentation generated from Doxygen comments will be integrated into the Markdown files via the Breathe extension.
+
+## Configuration
+
+The Markdown builder configuration is in `docs/conf.py`:
+
+- `markdown_http_base` - Base URL for external links (set to the hosted docs URL)
+- `markdown_uri_doc_suffix` - Suffix for document URIs (set to `.html` for compatibility)
+
+You can modify these settings if you need to adjust how links are generated in the Markdown output.
+
+## Troubleshooting
+
+### "Could NOT find Doxygen"
+Install Doxygen version 1.9.8 or later, or use the Docker build method.
+
+### "sphinx-build: command not found"
+Install Sphinx and related Python packages using `pip install -r docs/requirements.txt`.
+
+### "No module named 'sphinx_markdown_builder'"
+Install the sphinx-markdown-builder package: `pip install sphinx-markdown-builder`
+
+## Notes
+
+- The Markdown output is generated from the same source as the HTML documentation
+- Doxygen generates XML, which Breathe converts to Sphinx directives, which are then rendered to Markdown
+- Some complex HTML formatting may not translate perfectly to Markdown
+- The Markdown files are suitable for inclusion in other documentation systems or for viewing on platforms that render Markdown

docs/CMakeLists.txt

@@ -11,6 +11,10 @@ set(DOCS_SRC_DIR ${PROJECT_SOURCE_DIR}/docs)
 set(SPHINX_OPTS "-j auto -W --keep-going -T -v")
 separate_arguments(SPHINX_OPTS)
 
+# Options for markdown build (without -W to allow extension warnings)
+set(SPHINX_OPTS_MARKDOWN "-j auto --keep-going -T -v")
+separate_arguments(SPHINX_OPTS_MARKDOWN)
+
 add_custom_target(
     docs
     COMMAND ${CMAKE_COMMAND} -E env
@@ -24,3 +28,18 @@ add_custom_target(
     USES_TERMINAL
     COMMENT "Running Sphinx HTML build..."
 )
+
+add_custom_target(
+    docs-markdown
+    COMMAND ${CMAKE_COMMAND} -E env
+        ${SPHINX_BUILD}
+        -b markdown
+        -c ${DOCS_CFG_DIR}
+        -w ${DOCS_BUILD_DIR}/markdown_build.log
+        ${SPHINX_OPTS_MARKDOWN}
+        ${DOCS_SRC_DIR}
+        ${DOCS_BUILD_DIR}/markdown
+    COMMAND python3 ${DOCS_CFG_DIR}/fix_markdown_anchors.py ${DOCS_BUILD_DIR}/markdown
+    USES_TERMINAL
+    COMMENT "Running Sphinx Markdown build and fixing anchors..."
+)

docs/conf.py

@@ -32,7 +32,15 @@
     'sphinx.ext.autosectionlabel',
     'sphinxcontrib.jquery',
 ]
-suppress_warnings = ['autosectionlabel.*']
+
+# Only load sphinx_markdown_builder when building markdown
+if args.builder == 'markdown':
+    extensions.append('sphinx_markdown_builder')
+suppress_warnings = [
+    'autosectionlabel.*',
+    'config.cache',  # Suppress locale directory warnings
+    'misc.highlighting_failure',  # Suppress highlighting warnings
+]
 templates_path = ['_templates']
 exclude_patterns = ['build/']
 master_doc = 'index'
@@ -68,3 +76,45 @@
     'logo_only': True,
     'prev_next_buttons_location': None
 }
+
+# Options for Markdown output
+
+markdown_http_base = 'https://blues.github.io/note-c'
+markdown_uri_doc_suffix = '.html'
+
+# Custom handling for sphinx-markdown-builder compatibility
+def setup(app):
+    """Setup custom handlers for node types not supported by sphinx-markdown-builder."""
+    from docutils import nodes
+    from sphinx import addnodes
+    import logging
+
+    # Suppress the parallel reading warning for sphinx_markdown_builder
+    logger = logging.getLogger('sphinx')
+
+    # Check if we're using the markdown builder
+    if app.config._raw_config.get('_running_markdown_builder', False):
+        return
+
+    # Add a flag to detect when markdown builder is running
+    def builder_inited(app):
+        if app.builder.name == 'markdown':
+            app.config._running_markdown_builder = True
+            # Register handlers for unsupported node types
+            try:
+                from sphinx_markdown_builder.translator import MarkdownTranslator
+
+                # Handle desc_signature_line by treating it as a regular paragraph
+                def visit_desc_signature_line(self, node):
+                    pass
+
+                def depart_desc_signature_line(self, node):
+                    pass
+
+                MarkdownTranslator.visit_desc_signature_line = visit_desc_signature_line
+                MarkdownTranslator.depart_desc_signature_line = depart_desc_signature_line
+
+            except ImportError:
+                pass
+
+    app.connect('builder-inited', builder_inited)