Link from the docs to the homepage.

Hi, i want to link article from codex. @link(http://lampwww.epfl.ch/papers/idealhashtrees.pdf)(article) does not seem to work. How to add links?

I've spent the last few days looking for a documentation system to pull docstrings, convert them and emit markdown. I need a relatively rich input format and RST or Scriba look like they'll do the trick. I've got some legacy Scriba to work with too, and don't fancy converting it. Generally I like the concept of CommonDoc and I think good documentation needs to be a combination of hand-crafted and generated.

With this issue I'd like to explore what the best way to add a markdown package to emit docs/sections as markdown. In theory this should be simpler than the current HTML, since there's no formatting directives or style that need to be handled. The use case is to emit MD to be further processed by a documentation system generator, in this case Hugo. There are many styles ('themes') available, and this way I don't have to concern myself with styling and deployment.

How would one of you experienced with CommonDoc approach this? Initially I thought of:

1. Cloning the HTML emitter code paths however, to my eye, they're a bit convoluted and involve many systems and dependencies.
2. Walk the doc tree and use a generic template system like cl-template or html-template to emit the markdown. Despite the name, html-template is actually agnostic to the output format.
3. Maybe just walk the tree and manually emit?

I think any of these would work; the sticking point at the moment is the conversion of the docstring text from scriba to markdown, which I think happens in a combination of common-html and pandocl.

Any ideas?

So users can insert a tracking code into their HTML docs.

So far as I can tell from the reference, @ref[id=<something>] Is supposed to link to the thing identifed as @<something>[ref=<something>], but it links to a file named <something>, as well as setting the generated link's id to that something.

Could you tell me how insert the documentation for the method that uses qualifiers.
For example for method m-foo with qualifier :after
(defmethod m-foo :after ((x <a>) (y <b>) z) "Documentation for defmethod m-foo :after (x <a>) (y <b>) (z <c>)" t)

Just wondering, why Scriba, successor of Scribe, when we already have markup tailored for easy reading and writing - Markdown, AsciiDoc?

Currently generation fails if the docstring for something, in particular a slot or method is nil.

This is a little annoying for methods that I want to include in the documentation but don't really need a docstring (the docstring for the generic function and the type of the lambda lists should be sufficient), or when documenting a class with private slots.

I've created an example project https://cl-doc-systems.github.io/codex/ to demonstrate how Codex works. But the section where I use this code:

@cl:with-package[name="example/app"](
  @cl:doc(function foo)
)

instead of documentation on example/app:foo function Codex renders:

Expected Result

When I build the documentation locally, everything is OK:

Debug Information

Here is what I see in logs when building docs in GitHub Actions:

STYLE-WARNING:
   slot names with the same SYMBOL-NAME but different SYMBOL-PACKAGE (possible
   package problem) for class #<STANDARD-CLASS CODEX.MACRO:WITH-PACKAGE>:
       (COMMON-DOC.MACRO:NAME CODEX.MACRO::NAME)
STYLE-WARNING:
   slot names with the same SYMBOL-NAME but different SYMBOL-PACKAGE (possible
   package problem) for class #<STANDARD-CLASS CODEX.MACRO:WITH-PACKAGE>:
       (COMMON-DOC.MACRO:NAME CODEX.MACRO::NAME)
Inserting documentation for function "foo".
Inserting documentation for function "do-the-job".

and the same log it outputs locally.

Full sources are available here: https://github.com/cl-doc-systems/codex

The Question

How to debug what is happening to these blocks?

Requires some kind of LaTeX emitter library first.

Shouldn't be too hard to implement.

As far as I can tell there isn't any way to include documentation for a setf function, generic function, etc. I am happy to make a pull request for this if someone can point me in the right direction to fix it.

So i have generic function at, and generic function (setf at). I have no idea how to document second function.

I realized I made a typo in my recent PR which got merged (#24). Specifically, I accidentally added a ] near the end of line 36 in templates/static/nodes.css

• Minima
• Gamma

What would it take to make Codex parse the docstrings of function, classes, slots, etc. and include the documentation when it find a certain starting token in there.

I'd like to get rid of the manual definitions in manual.scr because I think it is a duplication and redundant. Usually you are in the source codes and write the docstrings anyway.

Common Lisp has a documentation method.
Suppose that the strings of documentation are generated differently,
for example for different localizations.

In my opinion the best behavior of codex would be to extract
docstrings using the documentation method rather than parsing
the source form.

(defun func (a b &optional (c "") (l 1))
    "docstring"
    (declare (ignore a b c l))
  t)

(setf (documentation #'func 'function) "NEW DOCSTRING")

CODEX::FUNC
  [symbol]

FUNC names a compiled function:
  Lambda-list: (A B &OPTIONAL (C "") (L 1))
  Derived type: (FUNCTION (T T &OPTIONAL T T)
                 (VALUES (MEMBER T) &OPTIONAL))
  Documentation:
    NEW DOCSTRING
  Source form:
    (LAMBDA (A B &OPTIONAL (C "") (L 1))
      "docstring"
      (DECLARE (IGNORE A B C L))
      (BLOCK FUNC T))

Although scribe is fine and easy to learn, many people use markdown these days, and it has the advantage of being more human readable for people browsing the source code directly.