fisxoj / coo Goto Github PK

View Code? Open in Web Editor NEW

13.0 3.0 3.0 63 KB

Documentation tools for common lisp

Common Lisp 76.45% CSS 21.61% Shell 1.05% Dockerfile 0.89%

docutils common-lisp documentation

coo's People

Contributors

Stargazers

Watchers

Forkers

vindarel davidalphafox svetlyak40wt

coo's Issues

Plugins and user-modifiable templates

Add ability to override rst templates
Add plugin loading for extra functionality (github links, &c.)

Switch to using rove for tests

I like not having to type plan and finalize.

Reference symbols in COMMON-LISP to the hyperspec

Please, add a link to the documentation into the GitHub's sidebar

This link https://fisxoj.github.io/coo/ can be also added to the GitHub project's about section. This will make it discoverable.

Can not copy <my-project>/default.css

Trying out coo (even though I can't tell what it brings out of the box compared to cl-docutils ;) ), it tries to copy default.css giving it the path of the current relative pathname.

Mark imported symbols as references to other packages

Even if a package re-exports a symbol, it's better to point to the package where it's defined and exported than to list it as though it were defined in that package.

Document class slots

Incude a table of contents on each page

Should list symbols in the current package and provide at least a link back to the top-level page.

Possibly, should list other packages in the sidebar.

Improve styles

Figure out how to hook into cl-docutils so that the output is more modern and pleasant...

Prior art:

Might be able to snag a stylesheet from one of the python ones since maybe they're using something docutils like.

Link superclasses to class definition

Superclasses should link to the documentation for each superclass if possible.

Doesn't compile on CCL

Here is a stack trace I copied from Sly's debugger.

Unknown character name - "Form" .
   [Condition of type SIMPLE-ERROR]

Restarts:
 0: [RETRY-COMPILE-FILE] Retry compiling #P"/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"
 1: [SKIP-COMPILE-FILE] Skip compiling #P"/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"
 2: [RETRY] Retry compiling #<CL-SOURCE-FILE "pp-toml" "pp-toml">.
 3: [ACCEPT] Continue, treating compiling #<CL-SOURCE-FILE "pp-toml" "pp-toml"> as having been successful.
 4: [RETRY] Retry ASDF operation.
 5: [CLEAR-CONFIGURATION-AND-RETRY] Retry ASDF operation after resetting the configuration.
 --more--

Backtrace:
 0: (#<Anonymous Function #x30000072F1EF> #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> #\\ NIL)
 1: (CCL::READ-DISPATCH #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> #\#)
 2: (CCL::%PARSE-EXPRESSION #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> #\# (NIL))
 3: (CCL::%READ-LIST-EXPRESSION #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> (NIL) #\))
 4: (CCL::READ-LIST #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> NIL #\))
 5: (CCL::%PARSE-EXPRESSION #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> #\( NIL)
 6: (CCL::%READ-FORM #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> 0 NIL)
 7: (CCL::READ-CONDITIONAL #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> #\- NIL)
 8: (CCL::READ-DISPATCH #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> #\#)
 9: (CCL::%PARSE-EXPRESSION #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> #\# (NIL))
10: (CCL::%READ-LIST-EXPRESSION #<BASIC-FILE-CHARACTER-INPUT-STREAM ("/Users/mb/quicklisp/dists/quicklisp/software/pp-toml-20180228-git/pp-toml.lisp"/4 UTF-8) #x3020051D707D> (NIL) #\))

May be a docparser issue - but "unexpected indentation" error?

Just tried running coo on postmodern. It was happily running away and then suddenly threw up on one file.

By the way, it threw an error, giving a line number, but not the file name (grep tells me that it s prepare.lisp).

It looks like it is upset when there is demonstration lisp code in a document string.

Figure out setting up coo as part of a CI process

It would be best if it were possible to generate the docs as part of CI and commit them there once tests pass. Would be good to set up and document.

Fails when package name has a slash (/)

The documentation generation fails if the package name has a "/" on it, because this "/" goes straight into the pathname name and thus it's interpreted like a directory separator.

(defun document-package (package-index &key keep-rst (base-path #P"docs/"))
 "Generates documentation in html form for :param:`package-index`.

The documentation file will have the pathanme ``{{base-path}}{{package-name}}.html``, so a package named ``cool-package`` with :param:`base-dir` ``docs/`` will have the generated pathame ``docs/cool-package.html``.

If :param:`keep-rst` is truthy, don't delete the intermediate restructured text file."

 (let* ((pathname (make-pathname :defaults base-path
                                 :name (-> package-index docparser:package-index-name string-downcase)
                                 :type "rst"
                                 :version nil))
        (coo.roles:*context-package* (find-package (docparser:package-index-name package-index)))
        (args (list :variables nil
                    :functions nil
                    :macros nil
                    :generic-functions nil
                    :structures nil
                    :classes nil)))

The problem is at name (-> package-index docparser:package-index-name string-downcase) : pathname is not filtering the package-index's name.

If this package name has a slash (/) (for example "mypackage/utils", then it becomes part of the pathname. It shouldn't.

The system needs to filter the package names accordingly.

Explore replacing cl-docutils

I started with this because it was an existing docutils implementation, but it's proving pretty difficult to work with

Controlling html output is difficult
- limits styling
- limits decorations like table of contents, border matter like links to other packages
can't figure out how to work with the transform system
- can't put coo's name/link in the footer
- it's been hard to muffle some errors

I might explore a new implementation of an rst parser in another repo in the meantime.