<commit_before>j-plankton.documentation
========================

This is a simple system to define documentation right into your common
lisp code.  This is mostly for pages of documentation that are not
nessesarily API docs for methods, but more general overview pages,
usage tips, etc.

Documentation in this way is defined in terms of "sections", each of
which contains a set of "blocks" of documentation.  The format of the
documentation is pecified *per-block* and defaults to markdown format.
More importantly, documentation of other sections defined can be
included ina section (thereby mking sub-sections!).  Once a sectio has
been defined (using (defsection)) then one can convert a section into
a full documentation with a given format (say HTML, Mardown, latex,
etc...) using (materialize-documentation).

One of the best features of defsection is that blocks may have
completely different formats when written, so one can freely mix Latex
formatted documentation with Mardown.  Each block type has a concept
of whether they require leading/trailing newlines when materializing.

defsection
==========

The defsection macro is the starting point and only macr a user needs to create documentation.  The simple usage is as follows:

    (defsection (<name> <title>)
		<block 0>
		<block 1>
		...
		)

<name>: a symbol, usually preffixed by '@', such as @intro.  This
symbol will be used as the section id by first calling (labelize-name)
on it's string representation.  The symbol will be globally bound with
the section object defined by defection.

<title> : a string represneting a title/subtitle section heading

<block N> : a block descriptor, documentated below

After a call to (defsection ...) we will have created a new global
binding to the given symbol <name> with a section-t object.  To
generate the codumentation for a section, we can the ncall
(materialize-documentation <name>)


blocks
======

The heart of defsection are the <block N> definitions inside of it.  A
block definition is a user-extendible syntax for creating different
logical chuncks of documetatation, where the logical break includes
the format being used to initially represent the documentation.

A string by itself will be treated as a text block with Mardown format.

Alternatively, one can expresilly choose hte format for a text block
by having a block descriptor as:

	(:<format> <text>)

Where :<format> is a keyword format specifier such as :markdown, :latex, etc...

To creat rbritary types of blocks we use the following syntax:

	(:class <class-name> <class-args>)

Which will fowards <class-args> to (make-instance '<class-name> <class-args>)


Example
=======

(defsection (@impl-note "IMPL Note")
	"We are using the algorithm by Jorkas, which implies the following condition: "
	(:latex "$x_i \le Z^i_k \forall k$ iff. ....))

(defsection (@intro "Intro")
	"Some sample introduction using *Mardown*")

(defsection (@doc "Documentation for X")
	@intro
	@impl-note)

<commit_msg>formated example to look like code (it is!)<commit_after>j-plankton.documentation
========================

This is a simple system to define documentation right into your common
lisp code.  This is mostly for pages of documentation that are not
nessesarily API docs for methods, but more general overview pages,
usage tips, etc.

Documentation in this way is defined in terms of "sections", each of
which contains a set of "blocks" of documentation.  The format of the
documentation is pecified *per-block* and defaults to markdown format.
More importantly, documentation of other sections defined can be
included ina section (thereby mking sub-sections!).  Once a sectio has
been defined (using (defsection)) then one can convert a section into
a full documentation with a given format (say HTML, Mardown, latex,
etc...) using (materialize-documentation).

One of the best features of defsection is that blocks may have
completely different formats when written, so one can freely mix Latex
formatted documentation with Mardown.  Each block type has a concept
of whether they require leading/trailing newlines when materializing.

defsection
==========

The defsection macro is the starting point and only macr a user needs to create documentation.  The simple usage is as follows:

    (defsection (<name> <title>)
		<block 0>
		<block 1>
		...
		)

<name>: a symbol, usually preffixed by '@', such as @intro.  This
symbol will be used as the section id by first calling (labelize-name)
on it's string representation.  The symbol will be globally bound with
the section object defined by defection.

<title> : a string represneting a title/subtitle section heading

<block N> : a block descriptor, documentated below

After a call to (defsection ...) we will have created a new global
binding to the given symbol <name> with a section-t object.  To
generate the codumentation for a section, we can the ncall
(materialize-documentation <name>)


blocks
======

The heart of defsection are the <block N> definitions inside of it.  A
block definition is a user-extendible syntax for creating different
logical chuncks of documetatation, where the logical break includes
the format being used to initially represent the documentation.

A string by itself will be treated as a text block with Mardown format.

Alternatively, one can expresilly choose hte format for a text block
by having a block descriptor as:

	(:<format> <text>)

Where :<format> is a keyword format specifier such as :markdown, :latex, etc...

To creat rbritary types of blocks we use the following syntax:

	(:class <class-name> <class-args>)

Which will fowards <class-args> to (make-instance '<class-name> <class-args>)


Example
=======

	(defsection (@impl-note "IMPL Note")
		"We are using the algorithm by Jorkas, which implies the following condition: "
		(:latex "$x_i \le Z^i_k \forall k$ iff. ....))

	(defsection (@intro "Intro")
		"Some sample introduction using *Mardown*")

	(defsection (@doc "Documentation for X")
		@intro
		@impl-note)


{'fraction_non_alphanumeric': 0.08202995008319468, 'fraction_numerical': 0.0006655574043261231, 'mean_word_length': 4.464545454545455, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7130432', 'n_tokens_mistral': 1673, 'n_tokens_neox': 1583, 'n_words': 851}