.. index:: autodoc-fs,gema,py.sphinx
 
.. _autodoc-fs:
 
.. Created autodoc-fs.rst: Fri 29 Jul 2022 13:50:01 AEST 
.. Full Path: /home/tp/mecrisp-unofficial-doc/autodoc-fs.rst 
.. Author Copyright 2022 by t.j.porter <techman001@protonmail.com> 
.. Made by /home/tp/projects/scripts/makerst.sh -->/usr/local/bin/makerst 
.. license: MIT, please see COPYING 
 
AutodocFs
=========

The Problem
-----------
One of the very time consuming parts of writing source documentation is gathering all the project definitions, adding the section/subsection/ in-text-formatting and so on before the actual content can be composed. This can be a contributing factor for why it never gets done.

My doc sites use the very capable py.sphinx program to produce HTML pages for the viewer. While py.sphinx is very easy to use, automation by way of shell scripts, Makefiles and methods as described here can drastically shorten the effort needed.

The less time I need to spend creating documentation, the more time I can spend designing/prototyping/building hardware and writing crap Forth code!

My Solution
------------

AutodocFs
^^^^^^^^^
AutodocFs is a system I'm working on which can parse a complete Forth project source-file into formatted HTML documentation.

Source to HTML
~~~~~~~~~~~~~~
1) View the :ref:`Forth source-code<allsource.fs.source.rst.link>`. 
2) View the :ref:`ReST documentation template<allsource.fs.rst.rst.link>` generated by *AutodocFs*.
3) View the :ref:`HTML view of the documentation<allsource.fs.rst.link>` generated by py.sphinx.

Features
~~~~~~~~
* Adds a unique page label: "$(OUTFILE).link" to the first line of the $(OUTFILE).
* Inserts the DAY and DATE to the $(OUTFILE)
* Adds an INDEX for every Word. If you click on :ref:`genindex` then on '-usb' you will see it's one of the allsource.fs.rst links.
* Auto subsection formatting: Counts the number of characters in each Word then adds the subsection formatting character "-" of the correct length underneath it.
* Displays the ( Stack Comment ) contents.
* NEW: Duplicate Word alert and list.
  
Bugs
~~~~
A few minor annoyances, nothing serious. 

How AutodocFs Work?
-------------------
Using `Gema <http://sourceforge.net/projects/gema>`_, a text preprocessor, the Forth Source code is parsed for definitions of the form below:
::

 \:\S*\S(\SX--Y\S)\S*\S\;

In other words for a definition to be recognised it must :

1) start with a COLON. This can be the first character in a line or preceded by one or more SPACES.
2) the COLON must be followed by one or more SPACES
3) the definition name can be any character(s) but must be followed by one or more SPACES
4) next is the LEFT BRACE followed by one or more SPACES
5) X can be null or any character(s) and is the STACK COMMENT INPUT
6) next, a pair of hyphens are required
7) Y can be null or any character(s) and is the STACK COMMENT OUTPUT followed by one or more SPACES.
8) A RIGHT BRACE followed by one or more SPACES.
9) any character(s) followed by one or more SPACES.
10) finally, a SEMI COLON to terminate the definition.

Everything after the SEMI COLON (item 10) is discarded. If definitions do not conform to this pattern *exactly*, they are ignored.

.. Note:: before Gema processing, the source file is stripped of all comments denoted by a leading backslash.


Gema
----
http://sourceforge.net/projects/gema/

.. note:: Gema parses each line with the syntax on the left of the "=" and replaces it with the string on the right.

AutodocFs Makefile
------------------
For FreeBSD, should work on Linux etc.
::

 all: create

 .PHONY:
 create:
   echo .. _$(SRCFILE).link: > $(OUTFILE)
   echo $(BLANKLINE) >> $(OUTFILE)
   echo $(TITLE) >> $(OUTFILE)
   echo $(TITLE1) >> $(OUTFILE)
   date >> $(OUTFILE)
   echo $(BLANKLINE) >> $(OUTFILE)
   gema -t -nobackup -line $(SRCFILE) -f delcomments.pat > $(INTERMEDIATE)
   gema -t -nobackup -line -match $(INTERMEDIATE) -f dup.pat > $(WORDSONLY)
   sort $(WORDSONLY) > $(SORTED)
   uniq -d $(SORTED) $(DUPLICATES)
   gema -t -nobackup  -match $(INTERMEDIATE) -f main.pat >> $(OUTFILE)
   sh duplicates-detected.sh

AutodocFs Gema Pattern Files
----------------------------

delcomments.pat
^^^^^^^^^^^^^^^
::

 ! Removes comments, Words only
 \\ *\n=\n

dup.pat
^^^^^^^
List just the Word names to be used for finding duplicates
::

 \:\S*\S(\S*\S)\S=$1\n

main.pat
^^^^^^^^^
The heavy lifter.
::

 \:\S*\S(\S*--*\S)\S*\S\;=.. index:: $1\n\n$1\n @repeat{@length{$1};-} \n::\n\n  ( $2--$3 )\n\n\n\n

duplicates-detected.sh
^^^^^^^^^^^^^^^^^^^^^^
::

 #!/bin/sh
 if [ -s 'duplicates.fs' ]
 then echo "
   DUPLICATE WORDS DETECTED !!!
   DUPLICATE WORDS DETECTED !!!
   DUPLICATE WORDS DETECTED = !!!"
   cat 'duplicates.fs'
 fi

.. note:: Any duplicate Word names will be listed in duplicates.fs