Merge pull request #2 from 40ants/commondoc-stage

[WIP] Use CommonDoc for intermediate documentation representation

.gitattributes

@@ -0,0 +1 @@
+static/* linguist-vendored

.gitignore

@@ -5,4 +5,7 @@ test/data/tmp/
 world/
 doc/
 docs/
+new-docs/
 .qlot/
+/coverage/
+.DS_Store

40ants-doc-full.asd

@@ -5,11 +5,12 @@
   :version "0.1.0"
   :author "Alexander Artemenko"
   :mailto "svetlyak.40wt@gmail.com"
-  :homepage "http://40ants.com/doc"
+  :homepage "https://40ants.com/doc"
   :bug-tracker "https://github.com/40ants/doc/issues"
   :source-control (:git "https://github.com/40ants/doc.git")
-  :description "Documentation generator for 40ANTS-DOC (based on MGL-PAX). You will need to load this system, to build documentation for a library which uses 40ANTS-DOC system."
+  :description "Documentation generator. You will need to load this system, to build documentation for a library which uses 40ANTS-DOC system."
   :class :package-inferred-system
   :pathname "src"
   :depends-on ("40ants-doc/full")
   :in-order-to ((asdf:test-op (asdf:test-op "40ants-doc-test"))))
+

40ants-doc-test.asd

@@ -5,7 +5,11 @@
   :class :package-inferred-system
   :pathname "test"
   :depends-on ("40ants-doc-test/test-transcribe"
-               "40ants-doc-test/test")
+               "40ants-doc-test/test"
+               "40ants-doc-test/xref"
+               "40ants-doc-test/locatives"
+               "40ants-doc-test/utils-test"
+               "40ants-doc-test/markdown")
   :perform (test-op (op c)
                     (unless (symbol-call :rove :run c)
                       (error "Tests failed"))))

40ants-doc.asd

@@ -5,10 +5,10 @@
   :version "0.1.0"
   :author "Alexander Artemenko"
   :mailto "svetlyak.40wt@gmail.com"
-  :homepage "http://40ants.com/doc"
+  :homepage "https://40ants.com/doc"
   :bug-tracker "https://github.com/40ants/doc/issues"
   :source-control (:git "https://github.com/40ants/doc")
-  :description "Documentation generator, based on MGL-PAX. Allows to put documentation inside lisp files and cross-reference between different entities."
+  :description "Allows to put documentation inside lisp files and cross-reference between different entities. Based on MGL-PAX."
   :class :package-inferred-system
   :pathname "src"
   :depends-on ("40ants-doc/core"
@@ -17,6 +17,8 @@
   :in-order-to ((asdf:test-op (asdf:test-op "40ants-doc-test"))))
 
 
+(asdf:register-system-packages "common-html" '("COMMON-HTML.EMITTER"))
+
 (asdf:register-system-packages "3bmd-ext-code-blocks" '("3BMD-CODE-BLOCKS"))
 
 (asdf:register-system-packages "swank" '("SWANK-BACKEND"

ChangeLog.md

@@ -0,0 +1,107 @@
+<a id="x-2840ANTS-DOC-2FCHANGELOG-3A-40CHANGELOG-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>
+
+# Changes
+
+<a id="x-2840ANTS-DOC-2FCHANGELOG-3A-3A-7C0-2E2-2E0-7C-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>
+
+## 0.2.0
+
+* Now defsection does not exports symbols by default
+
+* You can render documents in multiple formats in a single run having cross links.
+  For example shorter `README`.md could mention symbols and have correct
+  links to the full documentation
+
+* "Clean" `URL`s are supported out of the box.
+
+* Now defsection does not export nor mentioned symbols nor the name of the section
+  It is better to have explicit exports.
+
+* [`40ants-doc/locatives:include`](e263) locative now does not support `:HEADER`, `:FOOTER` and some other arguments. Use `:LANG` argument instead.
+
+* Added code highlighting using Highlight.js library.
+
+* Added search form which uses index in browser. `JS` code was taken from
+  [Sphinx][140c] documentation builder.
+
+* Elisp code for transcriptions was fixed and now should word not
+  only with `SLIME`, but also with `SLY`.
+
+* [`40ants-doc:defsection`](3e7c) macro now does not generate export code
+  if `:EXPORT` argument is `NIL`.
+
+* Functions `UPDATE-ASDF-SYSTEM-HTML-DOCS` and `UPDATE-ASDF-SYSTEM-README`
+  were replaced with [`40ants-doc/builder:update-asdf-system-docs`](f11d), which also supports
+  ChangeLog.md generation. Use [`40ants-doc/changelog:defchangelog`](28eb) to define versions.
+
+* Variables `*DOCUMENT-HTML-MAX-NAVIGATION-TABLE-OF-CONTENTS-LEVEL*` and
+  `*DOCUMENT-MAX-TABLE-OF-CONTENTS-LEVEL*` were removed. Probably we'll return this
+  feature back in other form, to restrict `TOC`'s size.
+
+* Removed `LOCATE-AND-DOCUMENT` generic function.
+
+* Links to the GitHub now are generated automatically,
+  if [`40ants-doc/builder:update-asdf-system-docs`](f11d) function is used
+  and system definition has a `:SOURCE-CONTROL` slot.
+
+* Generic functions `COLLECT-REACHABLE-OBJECTS` and `LOCATE-AND-COLLECT-REACHABLE-OBJECTS`
+  were removed.
+
+* Variables `*DOCUMENT-LINK-SECTIONS*`, `*DOCUMENT-TEXT-NAVIGATION*` and `*DOCUMENT-FANCY-HTML-NAVIGATION*` were removed.
+
+* Variable `*DOCUMENT-MIN-LINK-HASH-LENGTH*` was removed. Use `COMMONDOC-MARKDOWN:*MIN-LINK-HASH-LENGTH*`
+
+* Functions [`40ants-doc/builder:update-asdf-system-docs`](f11d) and [`40ants-doc/builder:render-to-files`](084c)
+  now accept `WARN-ON-UNDOCUMENTED-PACKAGES` argument and `CLEAN-URLS` argument.
+
+* Variable `*DOCUMENT-MARK-UP-SIGNATURES*` was removed.
+
+* Added `DOWNCASE-UPPERCASE-CODE` argument instead of `*DOCUMENT-DOWNCASE-UPPERCASE-CODE*`.
+  This argument is true by default.
+
+* Added warnings on symbols, referenced like internals, using `::`.
+
+<a id="x-2840ANTS-DOC-2FCHANGELOG-3A-3A-7C0-2E1-2E0-7C-2040ANTS-DOC-2FLOCATIVES-3ASECTION-29"></a>
+
+## 0.1.0
+
+* Project forked from [`MGL-PAX`][7927].
+  Code refactored into the package inferred system and core is separated
+  to have minimum dependencies.
+
+* Fixed displaying docstring for constant locative.
+
+* Include locative was fixed for files with unicode characters
+  file-subseq function was rewritten.
+
+* Locatives can be specified without a package prefix inside the defsection
+  because all locative symbols now live in [`40ants-doc/locatives`](dd8b) package.
+
+* Function update-asdf-system-readmes was renamed to update-asdf-system-readmes and now
+  it generates only one `README` file.
+
+* Tests were rewritten to use Rove and to support `(asdf:test-system :40ants-doc)`.
+
+* Removed `MGL-PAX:DEFINE-PACKAGE` macro. An `UIOP:DEFINE-PACKAGE` can be used instead.
+
+* Now builder issues a warning if it wasn't able to find a symbol mentioned in the docstring.
+
+* Uppercase word should have at least two charaters to be resolved as a symbol.
+
+* Improved work with package inferred systems. For examples, when fixed the
+  automatic symbol rendering for case when documentation section and
+  referenced objects are in different packages.
+
+* Allowed to reference objects using keywords.
+
+* Fixed docstring extraction for compiler macro.
+
+
+[7927]: https://github.com/melisgl/mgl-pax
+[140c]: https://www.sphinx-doc.org/
+[dd8b]: index.html#x-28-23A-28-2820-29-20BASE-CHAR-20-2E-20-2240ANTS-DOC-2FLOCATIVES-22-29-20PACKAGE-29
+[084c]: index.html#x-2840ANTS-DOC-2FBUILDER-3ARENDER-TO-FILES-20FUNCTION-29
+[f11d]: index.html#x-2840ANTS-DOC-2FBUILDER-3AUPDATE-ASDF-SYSTEM-DOCS-20FUNCTION-29
+[28eb]: index.html#x-2840ANTS-DOC-2FCHANGELOG-3ADEFCHANGELOG-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29
+[e263]: index.html#x-2840ANTS-DOC-2FLOCATIVES-3AINCLUDE-20-2840ANTS-DOC-2FLOCATIVES-3ALOCATIVE-29-29
+[3e7c]: index.html#x-2840ANTS-DOC-3ADEFSECTION-20-2840ANTS-DOC-2FLOCATIVES-3AMACRO-29-29