fisxoj / coo Goto Github PK
View Code? Open in Web Editor NEWDocumentation tools for common lisp
Documentation tools for common lisp
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.
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.
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) #\))
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.
Superclasses should link to the documentation for each superclass if possible.
I started with this because it was an existing docutils implementation, but it's proving pretty difficult to work with
I might explore a new implementation of an rst parser in another repo in the meantime.
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.
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.
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.
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.
I like not having to type plan
and finalize
.
This link https://fisxoj.github.io/coo/ can be also added to the GitHub project's about section. This will make it discoverable.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.