More C documentation

.github/workflows/pages.yml

@@ -11,24 +11,28 @@ jobs:
       with:
         submodules: true
 
-    - name: Install system dependencies
-      uses: awalsh128/cache-apt-pkgs-action@latest
+    - name: Use Python 3.12
+      uses: actions/setup-python@v5
       with:
-        packages: python3-clang python3-pip libclang-dev clang
-        version: 1.0
+        python-version: 3.12
+        cache: 'pip'
+        cache-dependency-path: |
+          python/requirements.txt
+          c/requirements.txt
+          docs/requirements.txt
 
     - name: Use Node.js 22
       uses: actions/setup-node@v3
       with:
         node-version: 22
 
-    - name: Use Rust stable
-      uses: actions-rs/toolchain@v1
-      with:
-        toolchain: stable
+    # - name: Use Rust stable
+    #   uses: actions-rs/toolchain@v1
+    #   with:
+    #     toolchain: stable
 
-    - name: Compile rust crate
-      run: cd docs && cargo build --manifest-path ../rust/Cargo.toml
+    # - name: Compile rust crate
+    #   run: cd docs && cargo build --manifest-path ../rust/Cargo.toml
 
     - name: Build sphinx docs
       run: make html

docs/c.rst

@@ -5,6 +5,22 @@ Euler C Implementation
     :start-line: 2
     :end-before: Problems Solved
 
+Library Code
+------------
+
+.. toctree::
+   :glob:
+   :numbered:
+   :maxdepth: 1
+
+   c/bcd
+   c/digits
+   c/factors
+   c/iterator
+   c/macros
+   c/math
+   c/primes
+
 Problems Solved
 ---------------
 

docs/c/factors.rst

@@ -0,0 +1,30 @@
+factors.h
+=========
+
+This file implements an :c:macro:`Iterator <IteratorHead>` that yields proper
+factors for a given number. It is generally used by first calling
+:c:func:`proper_divisor_count` and the :c:macro:`next`/:c:macro:`next_p` functions.
+
+.. c:namespace-push:: factors
+
+.. c:type:: factor_counter
+
+    .. c:member:: uintmax_t (*iterator_function)(factor_counter *it)
+
+    .. c:member:: bool exhausted : 1
+
+    .. c:member:: bool started : 1
+
+    .. c:member:: bool phase : 1
+
+    .. c:member:: uintmax_t target
+    
+    .. c:member:: uintmax_t current
+
+    .. c:function:: uintmax_t advance_factor_counter(factor_counter *fc)
+
+    .. c:function:: factor_counter proper_divisors(uintmax_t target)
+
+    .. c:function:: uintmax_t proper_divisor_count(uintmax_t target)
+
+.. c:namespace-pop::

docs/c/iterator.rst

@@ -0,0 +1,87 @@
+iterator.h
+==========
+
+.. c:namespace-push:: iterator
+
+.. c:macro:: IteratorHead(return_type, struct_type)
+
+    This macro allows a struct to implement my Iterator API, which is
+    heavily inspired by Python. You should put it at the top of a struct
+    like so:
+
+    .. code-block:: C
+        
+        struct counter {
+            IteratorHead(uintmax_t, counter);
+            uintmax_t idx;
+            uintmax_t stop;
+            intmax_t step;
+        };
+
+    It imparts the following internal properties.
+
+    .. c:member:: return_type (*iterator_function)(struct_type *it)
+
+        The function to advance the iterator and return the next element.
+
+    .. c:member:: bool exhausted : 1
+
+        An indicator that tells you if the iterator is exhausted.
+
+    .. c:member:: bool started : 1
+
+        An indicator that tells you if the interator has moved at all.
+
+    .. c:member:: bool phase : 1
+
+        An indicator that flips every time the iterator moves.
+
+.. c:macro:: IteratotionHead(it)
+
+    This macro implements the base functionality of all :c:macro:`Iterator <IteratorHead>` functions.
+    It must be at the top of all iteration functions, with the iterator passed
+    as an argument.
+
+.. c:macro:: IteratorInitHead(it, advance)
+
+    This macro implements the library-managed portion of iterator construction.
+    The first argument should be the uninitialized iterator, and the second
+    argument should be a pointer to its iteration function.
+
+.. c:macro:: next(state)
+.. c:macro:: next_p(state)
+
+    These macros implement the iteration operation. The only difference between
+    them is that :c:macro:`next` takes in a struct and
+    :c:macro:`next_p` takes a pointer. Both yield `return_type`.
+
+.. c:type:: counter
+
+    This is an example implementation of the :c:macro:`Iterator <IteratorHead>`
+    API used in this project. You can construct it using any of the factory
+    functions found below, and it is generally used much like Python's
+    :py:ref:`range` object.
+
+    .. c:member:: uintmax_t (*iterator_function)(counter *it)
+
+    .. c:member:: bool exhausted : 1
+
+    .. c:member:: bool started : 1
+
+    .. c:member:: bool phase : 1
+
+    .. c:member:: uintmax_t idx
+
+    .. c:member:: uintmax_t stop
+
+    .. c:member:: intmax_t step
+
+    .. c:function:: uintmax_t iterate_counter(counter *i)
+
+    .. c:function:: counter counter3(uintmax_t start, uintmax_t stop, intmax_t step)
+
+    .. c:function:: counter counter2(uintmax_t start, uintmax_t stop)
+
+    .. c:function:: counter counter1(uintmax_t stop)
+
+.. c:namespace-pop::

docs/c/p0001.rst

@@ -3,11 +3,10 @@ C Implementation of Problem 1
 
 View source code `here on GitHub! <https://github.com/LivInTheLookingGlass/Euler/blob/master/c/p0001.c>`_
 
-.. c:autosection:: Project Euler Problem 1
-   :file: p0001.c
+Includes
+--------
 
-.. c:autodoc:: p0001.c
-   :clang: -std=c11 -DAMD_COMPILER=0
+- `iterator.h <./iterator.html>`__
 
 .. literalinclude:: ../../c/p0001.c
    :language: C

docs/conf.py

@@ -11,9 +11,6 @@
 basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
 sys.path.insert(0, basedir)
 sys.path.insert(0, basedir + os.sep + 'python')
-hawkmoth_root = basedir + os.sep + 'c'
-hawkmoth_clang = ['-std=c11', '-DAMD_COMPILER=0']
-hawkmoth_source_uri = 'https://github.com/LivInTheLookingGlass/Euler/blob/master/{source}#L{line}'
 js_source_path = basedir + os.sep + 'javascript'
 rust_crates = ["../rust"]
 
@@ -40,7 +37,6 @@
     'sphinxcontrib.makedomain',
 ]
 if 'TERMUX_VERSION' not in os.environ:
-    # extensions.append('hawkmoth')
     extensions.append('sphinx_js')
     extensions.append('sphinx_rust')
 

docs/requirements.txt

@@ -1,8 +1,6 @@
 sphinx>=3.1
 sphinx-rtd-theme
 sphinx-js
-hawkmoth
-clang==14
 sphinx-csharp
 sphinxcontrib-makedomain
 sphinx_rust