First public commit.

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+tests/** linguist-detectable=false

.github/workflows/build.yml

@@ -0,0 +1,36 @@
+name: Build Status
+on: [push, pull_request]
+jobs:
+  python:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: "ubuntu-latest"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"] # Test the oldest and newest supported Python and Doxygen versions.
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Setup Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        sudo apt-get install doxygen
+    - name: Install package
+      run: |
+        pip install .
+    - name: Type checking
+      run: |
+        mypy --strict manos
+        mypy --strict tests
+    # The version of Ubuntu supported by GitHub Actions at the time of this writing is version 22.04 LTS.
+    # The latest version of Doxygen supported by Ubuntu 22.04 is 1.9.1 which is one patch version behind the
+    # minimum version required by Manos. The tests cannot be run on GitHub until they update to a version
+    # of Ubuntu that ships the expected Doxygen version (in the interm please run the tests locally).
+    # - name: Test
+    #   run: |
+    #     pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=manos --cov=tests --cov-fail-under=90

.gitignore

@@ -0,0 +1,15 @@
+.cache
+.ccls-cache
+.mypy_cache
+.eggs
+__pycache__
+*.egg-info
+*.pyd
+build
+local_install
+Testing
+dist
+tests/**/man
+tests/**/xml
+man
+xml

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+Dates are represented via [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
+
+## [0.9.1] - 2024-04-06
+
+Initial public release.

README.md

@@ -0,0 +1,86 @@
+# Manos
+
+**Manos** is a man page generator for C projects that use Doxygen for documentation generation.
+
+Manos does **not** require any modifications to your project, code comments, or Doxygen configuration file.
+
+[![Build Status](https://github.com/hgs3/manos/actions/workflows/build.yml/badge.svg)](https://github.com/hgs3/manos/actions/workflows/build.yml)
+
+## Why?
+
+Doxygen's man page output `(GENERATE_MAN = YES)` is less-than-stellar for projects written in the C programming language.
+For example the formatting and lack of per-function man page is atypical of what one would expect.
+Manos corrects these shortcomings by generating a man page per-function and with defacto standard formatting.
+
+## Installation
+
+Manos requires Python 3.10 or newer and Doxygen 1.9.2 or newer.
+
+Install the project through git checkout or install using your package management tool of choice.
+In these example `pip` is used.
+
+```
+$ pip install manos
+```
+
+or from repository checkout:
+
+```
+$ git clone https://github.com/hgs3/manos
+$ cd manos
+$ pip install .
+```
+
+## Usage
+
+Manos can be used from the command-line or as a Python module in code.
+
+After installing Manos, run the following command(s) substituting `Doxyfile` with the name of your Doxygen configuration file.
+If successful, there will be a directory created named `man` with your beautiful man pages.
+
+#### Command-line Usage
+
+```
+$ manos Doxyfile
+```
+
+#### Code Usage
+
+```py
+import manos
+manos.process("path/to/your/Doxyfile")
+```
+
+## Documentation
+
+Manos lets you customize the generated output in various ways.
+The complete list of customization options can be retrieved by running `manos -h` locally.
+
+Users on *nix systems are encouraged to review the man page for Manos with `man manos`.
+
+## Local Development
+
+If you intend to develop Manos locally, then first install the required development dependencies with:
+
+```
+$ pip install -r requirements.txt
+```
+
+Run unit tests with:
+
+```
+$ pytest
+```
+
+Run type checking with:
+
+```
+$ mypy --strict manos
+$ mypy --strict tests
+```
+
+## License
+
+**Manos** is available under the [GNU General Public License v3.0](LICENSE).
+
+The project is named after the no-buget horror [cult-classic film](https://en.wikipedia.org/wiki/Manos:_The_Hands_of_Fate) of the same name.

docs/manos.1

@@ -0,0 +1,185 @@
+.\" Copyright 2023-2024, Henry Stratmann III
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" 
+.\" Process this file with
+.\" groff -man -Tascii manos.1
+.\" --------------------------------------------------------------------------
+.TH "MANOS" "1" "April 4th 2024" "Manos 0.9.1"
+.SH NAME
+manos \- doxygen man page generator
+.\" --------------------------------------------------------------------------
+.SH SYNOPSIS
+.SY manos
+.OP \--help
+.YS
+.SY manos
+.OP \--version
+.YS
+.SY manos
+.OP \-\-filter PATTERN
+.OP \-\-synopsis TYPE
+.OP \-\-section NUMBER
+.OP \-\-preamble FILE
+.OP \-\-epilogue FILE
+.OP \-\-topic TEXT
+.OP \-\-footer\-middle TEXT
+.OP \-\-footer\-inside TEXT
+.OP \-\-header\-middle TEXT
+.OP \-\-autofill
+.OP \-\-output PATH
+.RI config
+.YS
+(See the OPTIONS section for details.)
+.\" --------------------------------------------------------------------------
+.SH DESCRIPTION
+Generate man pages for a C project using Doxygen for documentation generation where
+.I config
+is the name of the Doxygen configuration file.
+.PP
+The Doxygen configuration file is generated by running
+.BR doxygen(1)
+with the
+.B \-g
+option followed by an optional file name.
+If the file name is omitted then Doxygen will name it
+.BR Doxyfile .
+The contents of the file is a list of key/value pairs which need not be in any particular configuration for
+.BR manos (1).
+.PP
+Doxygen already supports generating man pages via the
+.SM GENERATE_MAN
+option, however, the output is less-than-stellar for projects written in the C programming language.
+For example the formatting and lack of per-function man page is atypical of what one would expect.
+Manos corrects these shortcomings by generating a man page per-function and with defacto standard formatting.
+.\" --------------------------------------------------------------------------
+.SH OPTIONS
+.TP
+.B "\-o \fIpath\fP"
+.TQ
+.B "\-\-output \fIpath\fP"
+Where to write the generated man pages.
+Where
+.I path
+is a path to a directory on the file system.
+If the option is omitted, then the output is written to the same directory as the Doxygen configuration file.
+The user must have write permissions to the output directory.
+.TP
+.B "\-s \fInumber\fP"
+.TQ
+.B "\-\-section \fInumber\fP"
+The man page section number.
+Must be an integer in the inclusive range 1-9.
+Defaults to 3.
+.TP
+.B "\-\-preamble \fIfile\fP"
+Content to prepend at the top of every generated man pages.
+Where
+.I file
+is the name of a file with the content.
+.TP
+.B "\-\-epilogue \fIfile\fP"
+Content to append to the bottom of every generated man pages.
+Where
+.I file
+is the name of a file with the content.
+.TP
+.B "\-\-topic \fItext\fP"
+Text centered in the footer.
+.TP
+.B "\-\-footer\-middle \fItext\fP"
+Text centered at the bottom of the man page.
+.TP
+.B "\-\-footer\-inside \fItext\fP"
+Text at the bottom left of the man page.
+.TP
+.B "\-\-header\-middle \fItext\fP"
+Text centered in the header of the man page.
+This need not be supplied.
+.TP
+.B "\-\-autofill"
+Populate header and footer text with auto-generated content.
+For example, the footer middle will be populated with the date the man page was generated.
+.TP
+.B "\-S \fItype\fP"
+.TQ
+.B "\-\-synopsis \fItype\fP"
+Include
+.I type
+in the SYNOPSIS section of header file man pages.
+Where
+.I type
+is one of
+
+\(bu \fBfunctions\fP
+.br
+\(bu \fBcomposites\fP
+.br
+\(bu \fBenums\fP
+.br
+\(bu \fBvariables\fP
+.br
+\(bu \fBtypedefs\fP
+.br
+\(bu \fBmacros\fP
+
+This option does not affect man pages for functions which implictly include the function signature that they document.
+.TP
+.B "\-F \fIpattern\fP"
+.TQ
+.B "\-\-filter \fIpattern\fP"
+XML files matching
+.I pattern
+are excluded from processing.
+.TP
+.B \-h
+.TQ
+.B \-\-help
+Display help text and exit.
+No other output is generated.
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Display version information and exit.
+No other output is generated.
+.\" --------------------------------------------------------------------------
+.SH RETURN CODES
+.B manos
+returns code
+.B 0
+on success, code
+.B 1
+on an error, and code
+.B 2
+if the program arguments are incorrect.
+.\" --------------------------------------------------------------------------
+.SH EXAMPLE
+Assuming a C project has a Doxygen configuration file named
+.BR Doxyfile ", "
+then run the following command from the same directory:
+.PP
+.EX
+$ manos Doxyfile
+.EE
+.PP
+This command will generate man pages for the project.
+They will be written to the same directory as the Doxygen configuration file.
+.\" --------------------------------------------------------------------------
+.SH REPOSITORY
+.UR https://GitHub.com/hgs3/manos
+https://GitHub.com/hgs3/manos
+.UE
+.ME
+.\" --------------------------------------------------------------------------
+.SH LICENSE
+Manos is distributed under an Open Source license.
+See the file "LICENSE" in the Manos source distribution for information on terms & conditions for accessing and otherwise using Manos and for a DISCLAIMER OF ALL WARRANTIES.