Interesting @U1G0HH87L, thanks for asking! Cljdoc is used to describe a library via its public API and associated articles. Does poly tool have a public API callable from Clojure or is it intended to be used as a command line tool only? We have a https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc which you might want to have a glance at, but in short, some notes of interest: • At this time cljdoc will only document libraries deployed to either clojars or maven central. • Cljdoc supports both Markdown and AsciiDoc for articles. My strong preference is AsciiDoc, but this is subjective. • Supported docstring formats are Markdown and plaintext. • Articles can be auto-discovered, but your https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#configuring-articles.

Hi! It's mainly a command line tool, polylith/clj-poly, but we also publish it as a library, polylith/clj-api, both on Clojars. I have started the migration of the documentation using AsciiDoc and I like it so far! If I get stuck or have more questions, I will reach out again, but right now I'm fine. Thanks!

I want to work locally and continuously show how the documentation looks like for the next unpublished 0.2.18 version (that I'm working towards). I don't want to publish anything at this stage, just work locally. I executed this, but it stopped when it couldn't find the 0.2.18 version:

~/source/polylith issue-318 *11 ?2 ❯ docker run --rm \                                                                                    8s 04:48:54
  --volume /Users/joakimtengstrand/source/polylith \
  --volume "$HOME/.m2" \
  --entrypoint clojure \
  cljdoc/cljdoc -Sforce -M:cli ingest \
    --project polyfy/polylith \
    --version 0.2.18 \
    --git /Users/joakimtengstrand/source/polylith \
    --rev $(git rev-parse HEAD)
WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested
2023-07-23T02:51:10.490Z [main] WARN FilenoUtil : Native subprocess control requires open access to the JDK IO subsystem
Pass '--add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED' to enable.
INFO [2023-07-23 02:52:23,332] main - cljdoc.server.system Migrating :up 001-create-builds-table
INFO [2023-07-23 02:52:23,391] main - cljdoc.server.system Migrating :up 002-create-releases-table
INFO [2023-07-23 02:52:23,409] main - cljdoc.server.system Migrating :up 003-add-api-git-columns-to-builds
INFO [2023-07-23 02:52:23,450] main - cljdoc.server.system Migrating :up 004-add-grimoire-style-tables
INFO [2023-07-23 02:52:23,518] main - cljdoc.server.system Migrating :up 005-add-analyzer-version-column-to-builds
INFO [2023-07-23 02:52:23,544] main - cljdoc.server.system Migrating :up 006-add-namespaces-count-column-to-builds
INFO [2023-07-23 02:52:23,566] main - cljdoc.server.system Migrating :up 007-builds-index
INFO [2023-07-23 02:52:23,605] main - cljdoc.server.system Migrating :up 008-create-stats-table
INFO [2023-07-23 02:52:23,637] main - cljdoc.server.system Migrating :up 009-add-error-info-column-to-builds
INFO [2023-07-23 02:52:23,660] main - cljdoc.server.system Migrating :up 010_convert_builds_error_info_from_exception_to_data
INFO [2023-07-23 02:52:23,683] main - migrations.010-convert-builds-error-info-from-exception-to-data rows to udpate: 0
INFO [2023-07-23 02:52:23,711] main - cljdoc.server.system Migrating :up 011-adjust-clojars-stats
INFO [2023-07-23 02:52:23,743] main - cljdoc.server.system Migrating :up 012-add-retry-count-to-releases
INFO [2023-07-23 02:52:23,776] main - cljdoc.server.system Starting :cljdoc/build-tracker
INFO [2023-07-23 02:52:23,779] main - cljdoc.server.system Starting :cljdoc/storage
INFO [2023-07-23 02:52:23,784] main - cljdoc.server.system Starting :cljdoc/analysis-service
** ERROR: **
Exception: #error {
 :cause Requested version cannot be found in configured repositories: [polyfy/polylith 0.2.18]
 :data {:project polyfy/polylith, :version 0.2.18}
 :via
 [{:type clojure.lang.ExceptionInfo
   :message Requested version cannot be found in configured repositories: [polyfy/polylith 0.2.18]
   :data {:project polyfy/polylith, :version 0.2.18}
   :at [cljdoc.server.api$kick_off_build_BANG_ invokeStatic api.clj 54]}]
 :trace
 [[cljdoc.server.api$kick_off_build_BANG_ invokeStatic api.clj 54]
  [cljdoc.server.api$kick_off_build_BANG_ invoke api.clj 43]
  [cljdoc.cli$build invokeStatic cli.clj 24]
  [cljdoc.cli$build invoke cli.clj 15]
  [cli_matic.core$invoke_subcmd invokeStatic core.cljc 546]
  [cli_matic.core$invoke_subcmd invoke core.cljc 525]
  [cli_matic.core$run_cmd_STAR_ invokeStatic core.cljc 589]
  [cli_matic.core$run_cmd_STAR_ invoke core.cljc 560]
  [cli_matic.core$run_cmd invokeStatic core.cljc 601]
  [cli_matic.core$run_cmd invoke core.cljc 591]
  [cljdoc.cli$_main invokeStatic cli.clj 90]
  [cljdoc.cli$_main doInvoke cli.clj 88]
  [clojure.lang.RestFn applyTo RestFn.java 137]
  [clojure.lang.Var applyTo Var.java 705]
  [clojure.core$apply invokeStatic core.clj 667]
  [clojure.main$main_opt invokeStatic main.clj 514]
  [clojure.main$main_opt invoke main.clj 510]
  [clojure.main$main invokeStatic main.clj 664]
  [clojure.main$main doInvoke main.clj 616]
  [clojure.lang.RestFn applyTo RestFn.java 137]
  [clojure.lang.Var applyTo Var.java 705]
  [clojure.main main main.java 40]]}

Yeah, local preview is a bit awkward/heavy/slow. It mimics production and therefore always works from jars. I tend to write a bb task to wrap all the work/verbosity. Here's an https://github.com/clj-commons/etaoin/blob/306ccc277d5543f1290dc69a63bf376d0af300df/bb.edn#L60-L61.

I have created a https://github.com/polyfy/polylith/blob/issue-318/bb.edn that has a working jar command that builds projects/poly/target/poly.jar. I copied https://github.com/polyfy/polylith/blob/issue-318/scripts/cljdoc_preview.clj and the helper directory from etaoin to my scripts directory and tried to update the https://github.com/polyfy/polylith/blob/186476f7ab2f309c432d51f2d26fa30b5ca91fe1/scripts/cljdoc_preview.clj#L28-L33. I'm quite sure I have to put in projects/poly/target/poly.jar somewhere in cljdoc_preview.clj, but unsure where and I probably missed some other things too. If/when you have time, please have a look!

There might be a lighter way, https://github.com/clj-commons/etaoin/blob/306ccc277d5543f1290dc69a63bf376d0af300df/script/cljdoc_preview.clj#L45-L47. I can get a bb task working for you, if you like.

I don't mind volunteering to do this sort of thing because it helps to remind me of the pain points, perhaps enough to someday do something about them!

For the constants, I think you only want to change project btw, but lemme give you a hand with this.

So @U1G0HH87L, if I understand correctly we have https://clojars.org/polylith/clj-poly and https://clojars.org/polylith/clj-api. Am I right in guessing that these two different artifacts should bring up the same articles on cljdoc? But maybe different API docs?

Yes, please contribute if you want (a PR or the way you like)! I want both to live in the same API doc, because both share almost the same set of components (remember, this is a Polylith codebase that can share code between artifacts). The articles are much more important than the API docs, but the latter would adds some value (the api component only exposes two functions). I want the articles to look similar to how the gitbook doc, including a left menu. Earlier I put all the documentation in a single readme.md, but that didn't give a good user experience because the file got too big.

Cljdoc currently works on at the granularity of a single artifact version. So it will analyze clj-poly and clj-api jars separately. But these jars will point back to the same git repo... so easy to have them share the same set of articles (or not, you can choose to https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#distinctly-configuring). But for clojure API docs, these come from analyzing the sources in the individual jar. So, as cljdoc stands today, these will be different for clj-poly and clj-api.

If we take a peek at what cljdoc is presenting for these artifacts today... https://cljdoc.org/d/polylith/clj-api/0.2.17-alpha and https://cljdoc.org/d/polylith/clj-poly/0.2.17-alpha I see many namespaces documented. I expect most of these are not part of the supported public API? If not, best to mark nses and optionally individual vars that are not public with :no-doc metadata.

The only functions that are exposed are these two in the https://github.com/polyfy/polylith/blob/issue-318/components/api/src/polylith/clj/core/api/interface.clj component, all the rest are implementation details. It would be nice if it was possible to specify what is exposed, and leave the rest. I just pushed more .adoc files to doc in the https://github.com/polyfy/polylith/tree/issue-318 branch.

On the other hand, we could also show all code and have a note somewhere how to use clj-api (this could live in the "poly tool"/poly-clj documentation).

This is how the polylith repository looks like. The components are in green, and the projects are in purple. You can see that the poly tool doesn't contain the api component, and that the api project doesn't contain the creator component (and others) or the poly-cli base (in blue). But they all live in the same monorepo.

> On the other hand, we could also show all code and have a note somewhere how to use clj-api By "show all code" do you mean document all namespaces? Are these something a user of polylith would use/call?

Or would they only call https://github.com/polyfy/polylith/blob/issue-318/components/api/src/polylith/clj/core/api/interface.clj?

Most people only use the poly command line tool (clj-poly). Just a very few (I know one) use the api component, which is only needed if you create polylith integrations.

Yes, document all namespaces.

On the other hand, people have access to all namespaces via github already, but my guess is that it could be good to have everything in one place (cljdoc).

I'm not sure I understand yet, I am polylith-naive, bear with me. If users of polylith will only use api, why would we document all namespaces? Will they also use those namespaces somewhere/somehow?

Or... are you documenting polylith internals?

I'm converting the poly https://polylith.gitbook.io/poly/, that today lives in gitbook. I don't think we need to publish the API of the api component, because it's just two tiny functions. I was just speculating if it could have some value to publish everything (all the source code, just as github does) as a complement to gitbook (I have no experience of cljdocs).

I think I understand now. Ideally cljdoc documents libraries for users. Someone reading library docs on cljdoc will expect a library's documented API to be nses and fns they can use and call and won't break with the next release. Not every library author does a good job of distinguishing their public API from implementation details, but ideally, they would.

So my general recommendation would be to only document the public API.

But... if you really want to document everything, a very strong note the articles would probably help users.

The main reason for moving to cljdoc is not to document the public API, but to move the documentation back to the repository where the code lives, so that they can be updated at the same time, in our commits. I think we can start out by not documenting everything (the API) and only concentrate on the migration of the poly tool doc.

Sounds good.

Hey, 'nother question: are clj-poly and clj-api always released together at the same time? Just wondering... if they aren't would that cause confusion/weirdness on from cljdoc perspective.

Yes, they are.

And they get the same versions.

I will spend the rest of today and tomorrow to finish the migration of the .adoc files. If you have time, it would be awesome if you could help out getting the bb.edn script to work (e.g. by creating a PR)!

(the doc command)

Ya, can certainly take a peek at that sometime my-today. I might be able to also turf some of those helper nses for the script. But now, gonna go enjoy a walk by the river!

Sounds great!

Heya @U1G0HH87L, a recent polylith change has me a bit confused. I'm looking to discover the current version, https://github.com/polyfy/polylith/blob/0cef90c9be86d0d6a52324ff5bcf6fb1a6bd1087/components/version/src/polylith/clj/core/version/interface.clj#L11`tool`https://github.com/polyfy/polylith/blob/0cef90c9be86d0d6a52324ff5bcf6fb1a6bd1087/components/version/src/polylith/clj/core/version/interface.clj#L11?

Current return for name off master is poly-0.2.18-issue205-01 which does not seem like a valid maven version.

Ahh, I see. Will change back and tell you when that is done!

I have changed back to how it was before. Now it should work.

Cool, thanks, I'll poke around more at this sometime my-today.

Hmm... @U1G0HH87L I've been working off the master branch so I can focus on the minimum needed for cljdoc preview. But maybe I should be working off the issue-318 branch?

Yeah... I probably should switch to issue-318 branch.

Yes, work on the issue-318 branch!

@U1G0HH87L, I'm not sure that jar building is working correctly in issue-318 branch. If I build the api jar likes so:

> clojure -T:build jar :project api

❯ unzip -l projects/api/target/api-thin.jar 
Archive:  projects/api/target/api-thin.jar
  Length      Date    Time    Name
---------  ---------- -----   ----
       82  2023-07-24 15:48   META-INF/MANIFEST.MF
        0  2023-07-24 15:48   META-INF/
        0  2023-07-24 15:48   META-INF/maven/
        0  2023-07-24 15:48   META-INF/maven/polylith/
        0  2023-07-24 15:48   META-INF/maven/polylith/clj-api/
     1779  2023-07-24 15:48   META-INF/maven/polylith/clj-api/pom.xml
      134  2023-07-24 15:48   META-INF/maven/polylith/clj-api/pom.properties
---------                     -------
     1995                     7 files

❯ clojure -T:build jar :project poly

❯ unzip -l projects/poly/target/poly-thin.jar 
Archive:  projects/poly/target/poly-thin.jar
  Length      Date    Time    Name
---------  ---------- -----   ----
       82  2023-07-24 15:49   META-INF/MANIFEST.MF
        0  2023-07-24 15:49   META-INF/
        0  2023-07-24 15:49   META-INF/maven/
        0  2023-07-24 15:49   META-INF/maven/polylith/
        0  2023-07-24 15:49   META-INF/maven/polylith/clj-poly/
     2352  2023-07-24 15:49   META-INF/maven/polylith/clj-poly/pom.xml
      135  2023-07-24 15:49   META-INF/maven/polylith/clj-poly/pom.properties
---------                     -------
     2569                     7 files

Will have a look.

I have pushed a fix, so you can try again @UE21H2HHD (I will also check).

Yeah, good stuff, I see .clj files in the jars now.

Perfect!

Thanks for helping out with this. It's late here. Will continue tomorrow.

Ya, my pleasure.

When you are refreshed: first crack at tweaking the doc task: https://github.com/polyfy/polylith/pull/319

@U1G0HH87L not sure if it is of interest but you can group articles under headings if you like. I see you've done that for https://polylith.gitbook.io/poly but not yet in issue-318 cljdoc.edn. AsciiDoc also has in-doc table of contents support, which you might, or might not, want to take advantage of. https://cljdoc.org/d/rewrite-clj/rewrite-clj/1.1.47/doc/user-guide might offer good examples for both the above. Hit me up if you want to learn more.

This is awesome! I have merged the PR, and will have a closer look. My plan is to make it work first, and then to make it look good! Thanks!

I got this error.

It fails when I run bb doc ingest (skip the first bb doc poly !).

Hmm... bb doc ingest is what I tried too, but with success. I'll take a peek my-tomorrow off a fresh pull of your branch. My-today is done!

Sounds good!

Did you do a bb doc start ?

Yes, started with that.

ok, good, will check with ya tomorrow!

When I try bb doc ingest poly it looks like it try to build doc for clj-api (you don't have to answer now!):

Good my-morning! I just retried from issue-318 branch, with success:

❯ bb doc start

[ TASK doc start ]---------------------------------------------------------------

[ Checking for updates ]---------------------------------------------------------
Using default tag: latest
latest: Pulling from cljdoc/cljdoc
Digest: sha256:2334c8e5a00aa334271515e719292af2aa6928ca9390557fea3771ca6b8d6438
Status: Image is up to date for cljdoc/cljdoc:latest


What's Next?
  View summary of image vulnerabilities and recommendations → docker scout quickview cljdoc/cljdoc

[ Starting cljdoc-server on port 8000 ]------------------------------------------
55b04c82457c82f7d61cfdd4d3841f764966a36202133eea62c4801c013ac70c

TASK doc done.

❯ bb doc ingest

[ TASK doc ingest ]--------------------------------------------------------------

-WARNING-------------------------------------------------------------------------
  There are changes that have not been committed, they will not be previewed     
 --------------------------------------------------------------------------------

[ installing poly to local maven repo ]------------------------------------------
Starting install for poly project.

Writing pom.xml...
Copying components/antq/src, components/change/src, components/clojure-test-test-runner/src, components/command/src, components/common/src, components/config-reader/src, components/creator/src, components/creator/resources, components/deps/src, components/file/src, components/git/src, components/help/src, components/image-creator/src, components/lib/src, components/migrator/src, components/overview/src, components/path-finder/src, bases/poly-cli/src, components/sh/src, components/shell/src, components/system/src, components/tap/src, components/test-runner-contract/src, components/test-runner-orchestrator/src, components/text-table/src, components/user-config/src, components/user-input/src, components/util/src, components/validator/src, components/version/src, components/workspace/src, components/workspace-clj/src, components/ws-explorer/src, components/ws-file/src...
Building jar target/poly-thin.jar...
Jar is built.
Installing polylith/clj-poly-0.2.18-issue318-02 to your local `.m2`
done.
Local install completed for poly project.

[ Ingesting project polylith/clj-poly 0.2.18-issue318-02 
  into local cljdoc database                             ]-----------------------
2023-07-25T13:27:30.312Z [main] WARN FilenoUtil : Native subprocess control requires open access to the JDK IO subsystem
Pass '--add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED' to enable.
INFO [2023-07-25 13:27:47,076] main - cljdoc.server.system Starting :cljdoc/build-tracker
INFO [2023-07-25 13:27:47,080] main - cljdoc.server.system Starting :cljdoc/storage
INFO [2023-07-25 13:27:47,083] main - cljdoc.server.system Starting :cljdoc/analysis-service
INFO [2023-07-25 13:27:49,981] clojure-agent-send-off-pool-0 - cljdoc.analysis.git Cloning Git repo from 
INFO [2023-07-25 13:27:59,479] clojure-agent-send-off-pool-0 - cljdoc.analysis.git Analyzing git repo at revision: d59f495c233e25efd30942df2c3413336000640f
INFO [2023-07-25 13:28:00,032] clojure-agent-send-off-pool-0 - cljdoc.server.ingest Importing Articles from 
INFO [2023-07-25 13:28:00,230] clojure-agent-send-off-pool-0 - cljdoc.analysis.service Starting local analysis for polylith/clj-poly 0.2.18-issue318-02 /root/.m2/repository/polylith/clj-poly/0.2.18-issue318-02/clj-poly-0.2.18-issue318-02.jar
INFO [2023-07-25 13:28:25,489] clojure-agent-send-off-pool-0 - cljdoc.analysis.service Got file from Local AnalysisService /tmp/cljdoc/analysis-out/cljdoc-analysis-edn/polylith/clj-poly/0.2.18-issue318-02/cljdoc-analysis.edn
INFO [2023-07-25 13:28:25,572] clojure-agent-send-off-pool-0 - cljdoc.server.ingest Verifying cljdoc analysis edn contents against spec
INFO [2023-07-25 13:28:25,572] clojure-agent-send-off-pool-0 - cljdoc.server.ingest Importing API into database polylith/clj-poly 0.2.18-issue318-02
INFO [2023-07-25 13:28:25,594] clojure-agent-send-off-pool-0 - cljdoc.storage.sqlite-impl version-id 1

TASK doc done.

❯ bb doc view

[ TASK doc view ]----------------------------------------------------------------

[ Waiting for cljdoc-server to become available ]--------------------------------
cljdoc-server container is running
reached 

[ opening  in browser ]

TASK doc done.

So... not sure yet what is different for us here, but I'm sure we can figure it out.

To your other question: > When I try bb doc ingest poly it looks like it try to build doc for clj-api I'm intending to use your build.clj jar fn here, but could be I don't understand something. Why does it look like it is building clj-api? Here's me calling the existing jar fn, do these look correct?

❯ clojure -T:build jar :project poly

Writing pom.xml...
Copying components/antq/src, components/change/src, components/clojure-test-test-runner/src, components/command/src, components/common/src, components/config-reader/src, components/creator/src, components/creator/resources, components/deps/src, components/file/src, components/git/src, components/help/src, components/image-creator/src, components/lib/src, components/migrator/src, components/overview/src, components/path-finder/src, bases/poly-cli/src, components/sh/src, components/shell/src, components/system/src, components/tap/src, components/test-runner-contract/src, components/test-runner-orchestrator/src, components/text-table/src, components/user-config/src, components/user-input/src, components/util/src, components/validator/src, components/version/src, components/workspace/src, components/workspace-clj/src, components/ws-explorer/src, components/ws-file/src...
Building jar target/poly-thin.jar...
Jar is built.

❯ clojure -T:build jar :project api 

Writing pom.xml...
Copying components/antq/src, components/api/src, components/change/src, components/common/src, components/config-reader/src, components/deps/src, components/file/src, components/git/src, components/image-creator/src, components/lib/src, components/path-finder/src, components/sh/src, components/system/src, components/test-runner-contract/src, components/text-table/src, components/user-config/src, components/user-input/src, components/util/src, components/validator/src, components/version/src, components/workspace/src, components/workspace-clj/src, components/ws-explorer/src...
Building jar target/api-thin.jar...
Jar is built.

Ah. I think you did uncover a bug in cljdoc-analyzer analysis duration reporting. (The Matcher exception you shared with me). I'll fix that and report back.

The poly.jar is an uberjar, while api.jar is a jar:

clojure -T:build uberjar :project poly
clojure -T:build jar :project api

Ah, I see. So, should your build.clj be deploying an uberjar? https://github.com/polyfy/polylith/blob/9053b190d5f3b0680ac4fe5c5f1851f7c0d40830/build.clj#L232-L254`jar`https://github.com/polyfy/polylith/blob/9053b190d5f3b0680ac4fe5c5f1851f7c0d40830/build.clj#L232-L254.

And poly is an uberjar because it is a tool, not a lib? Is that done for performance reasons only?

Yes, the poly tool is AOT compiled for performance reasons, and is started with a batch script with something like java -jar poly.jar that you put in your classpath.

But it has a built in https://github.com/polyfy/polylith/blob/issue-318/doc/shell.adoc that can be started with e.g. clojure -M:poly which allows you to pay the compilation cost only once.

We have the ci script https://github.com/polyfy/polylith/blob/issue-318/.circleci/config.yml.

amiright that you are deploying thin poly jar to clojars?

The build.clj script has recently been updated, so I need to take a look and compare it with how it looked before (e.g. the previous 0.2.17-alpha release, https://github.com/polyfy/polylith/blob/v0.2.17-alpha/build.clj).

I think you were still deploying the thin poly jar... lemme check on that. for ya...

Ya, if I download https://repo.clojars.org/polylith/clj-poly/0.2.17-alpha/clj-poly-0.2.17-alpha.jar and do an unzip -l on it, I only see .clj files. If there is any chance that clj-poly is to be used as a library, I think a thin jar is the way to go. Otherwise folks will curse you when their deps conflict with the uberjar .class files, no?

You can read about the different ways of using the poly tool in the https://github.com/polyfy/polylith/blob/issue-318/doc/install.adoc section, which also has a section "Polylith as a library" that explains how to use api. I think I mixed things up in my head, but now I remember how it is! What is in clojars is just plain jar files, containing source code, so that people can use it as libraries if they want (we dont want to AOT compile that code), but then we also have the AOT compiled "binary" poly tool in the github release. So everything is fine as it is I think!

Cool, that makes sense to me.

I would love to learn more about polylith in detail (I often wonder if cljdoc itself would benefit from being a polylith project), but for now I'll focus on what I need to learn to help you get a reasonable cljdoc workflow going.

I don't know if people use clj-poly or clj-api but I could ask the community. I releasing one of them would be enough, if I just put all components that they use (now they use about 90% of each other). Then we could release just one of them as a library.

Hmmm... that's probably a good idea. Then folks would not need to figure out which one to choose.

If you want, we could have a little session, where I explain everything and you can ask questions.

Thanks for that generous offer, I might take you up on that someday!

1. @U1G0HH87L I fixed the Matcher problem you shared here, when you have some time, please give bb doc ingest another whirl. It still might fail for you, but we might see the actual cause this time. 2. lemme know if you decide to merge clj-api and clj-poly to a single artifact, this would also make previewing docs simpler, I would think.

1. Will have a look right away. 2. Yes, let's only publish clj-poly.

Have you created a PR?

Nope, just changed cljdoc-analyzer which gets picked up automatically.

Gonna go enjoy some nature now, but I'll adjust doc task when I come back to only preview clj-poly. I'll generate a PR for that.

Okay, cool!

I could run bb doc ingest this time! It generates the API doc, but it didn' pick up the articles:

you might not have pushed your commits?

I have pushed the latest changes now.

Just two pages left to migrate! Question (AsciiDoc related). I added :toc: at the top of https://github.com/polyfy/polylith/blob/issue-318/doc/commands.adoc page, but with no affect. Another thing. I will be busy from now and up to an hour (if I don't answer).

I have added the https://github.com/polyfy/polylith/blob/issue-318/doc/cljdoc.edn, so don't know what I'm missing.

I think I got the links wrong. Should probably be "../readme.adoc" and "install.adoc". Will try that.

I updated the links, but still no articles found.

I'm back from my nature walk. I'll grab you branch and see what happens for me and report back.

For you adoc table of contents. You specify :toc: as an attribute of the title if you want your toc to appear right after the title.

= My title
:toc:

= My title
:toc: macro

Some other content

toc::[]

= My title
:toc: preamble

Some preamble words

== First section header

Note your in-doc toc will show on github as well, so easy to play there.

Okay, thanks.

The indentation looked strange in cljdoc.edn, so pushed a change.

Ya noticed, that, refetching... ok yes, that's better. But 2 things I noticed: docs are relative to git project root.. so "readme.adoc" and "doc/install.adoc" and it is :cljdoc.doc/tree not :cljdoc.tree . Here's rewrite-clj's cljdoc.edn for reference:

{:cljdoc.doc/tree
 [["Readme" {:file "README.adoc"}]
  ["Changelog" {:file "CHANGELOG.adoc"}]
  ["User Guide" {:file "doc/01-user-guide.adoc"}]
  ["Developer Guide" {:file "doc/02-developer-guide.adoc"}]
  ["Design" {}
   ["Merging rewrite-clj and rewrite-cljs" {:file "doc/design/01-merging-rewrite-clj-and-rewrite-cljs.adoc"}
    ["Namespaced Elements" {:file "doc/design/namespaced-elements.adoc"}]]
   ["API Differences" {}
    ["rwt-clj v0 vs rwt-cljs" {:file "doc/generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-cljs-lang-cljs.adoc"}]
    ["rwt-clj v0 vs rwt-clj v1" {:file "doc/generated/api-diffs/rewrite-clj-v0-lang-clj-and-rewrite-clj-v1-lang-clj.adoc"}]
    ["rwt-cljs vs rwt-clj v1"  {:file "doc/generated/api-diffs/rewrite-cljs-lang-cljs-and-rewrite-clj-v1-lang-cljs.adoc"}]
    ["rwt-clj v1 clj vs cljs all"  {:file "doc/generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj.adoc"}]
    ["rwt-clj v1 clj vs cljs public" {:file "doc/generated/api-diffs/rewrite-clj-v1-lang-cljs-and-rewrite-clj-v1-lang-clj-documented-only.adoc"}]]]
  ["Frequently Asked Questions" {:file "doc/03-faq.adoc"}]
  ["Contributing" {:file "CONTRIBUTING.md"}]
  ["Code of Conduct" {:file "CODE_OF_CONDUCT.md"}]
  ["Maintainer Guide" {:file "doc/04-maintainer-guide.adoc"}]]}

Okay, cool, will have a look.

Ok, I'll PR doc bb task to only deal with poly lib and drop support for api lib.

I commited these changes locally, while the server was running. Should it pick up the articles automatically, or do I need to restart the server, run ingest again, and stuff like that?

They are pushed now.

The way things work now you've actually gotta push them.

And then run ingest again.

Ok. Do I need to restart the server also?

Nope

See workflow from my https://github.com/polyfy/polylith/commit/956764740380dd199d8946e1a762aac33ee158a4.

Thanks.

Now it works! Thank you so much!

Sweet!

Will try to group the left menu, and stuff like that, but this is really good!

Well, glad you like it. And appreciate your patience with our currently rather heavy client side preview flow.

I will mostly work with one page at a time, and for that the preview in my IDE works pretty well. But yes, it would be cool if you could just point to the local git repository, and maybe get instant feedback in the browser when you change files, or something similar! But I understand why you decided to work against the jar, because that's the "truth" at least when you want to document libraries.

Yeah, but think client-side-first would have been more user-friendly. Always trade offs! I expect we can figure something out eventually.

Yes, things can always be improved! But this works perfectly fine for me right now.

That's good to know!

It will save me a lot of time and make it simpler for people to participate in making PR's.

While I think of them, two things come to mind while looking at your docs on cljdoc: 1. your images don't zoom when clicked. I found that helpful on your current non-cljdoc docs. 2. search will search your docs and API, this adds weight to only including your documented API otherwise folks will be finding internal stuff when they search.

Ping me when you've merged poly and api. I can help with point 2.

1. Do you have any idea why? 2. Okay, cool (that you can help with that). Will merge and tell you when that is done (in about 5 min).

Another thing. You said that you prefer AsciiDoc to Markdown. What are the biggest benefits do yo say?

I find it much more expressive and well-thought-out. I spend less time wondering how to render an effect that I want with adoc. In markdown I sometimes find myself delving into the limited HTML syntax it supports. Not so with adoc. And adoc has things like toc support and even primitive user variables.

But really, it is subjective, it is just my strong preference for writing docs.

Here's the promised PR: https://github.com/polyfy/polylith/pull/320

For the image zoom: just not an adoc/markdown feature. Not sure how we'd express that yet. Probably would not want it for all images. Could make those images links that click through to original on github I suppose. As a compromise.

I have merged the PR and pushed the "merge" so that poly now also include the api component and that the api project is dropped.

speedy!

When we release to Clojars next time, will all this documentation be automatically available for the users (I guess so)? Will a pdf also be available (I think I read that somewhere)?

Ok, my way to drop everything but your public API is to add :no-doc metadata to all but https://github.com/polyfy/polylith/blob/issue-318/components/api/src/polylith/clj/core/api/interface.clj. This might seem a little noisy but does give folks (and tools) reading your code some more info.

That sound ok to you?

That's totally fine with me, if you want to help out with that!

Happy to.

> When we release to Clojars next time, will all this documentation be automatically available for the users (I guess so)? yup and you can link to it in your README with a https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#badges if you like. > Will a pdf also be available (I think I read that somewhere)? Nope, we don't currently generate PDFs, but maybe that's an interesting idea! We do have support for offline docs for fans of tools like https://kapeli.com/dash. I'm not a user of such tools, but some folks love this kind of thing.

https://github.com/polyfy/polylith/blob/master/components/test-runner-contract/src/polylith/clj/core/test_runner_contract/interface.clj#L3 two protocols are also part of the public API.

Here you go: https://github.com/polyfy/polylith/pull/321

Merged. It looks really great already! I really like that we show what is part of the public API.

I'm missing the "copy" icon that turns up in the gitbook doc when hovering over a code block, e.g.:

Yes, good idea, https://github.com/cljdoc/cljdoc/issues so I don't forget!

Question. We don't release snapshots to Clojars today, but I push issues to the master branch continuously, before I publish a new release. Today these versions are named something like 0.2.18-issue318-02 . Would it be possible to release the cljdoc with a name like 0.2.18-SNAPSHOT for all releases up till the real 0.2.18 (regardless what's in the issue318-02 part)? I'm okay with releasing those snapshots to Clojars if needed.

I created issue https://github.com/cljdoc/cljdoc/issues/786.

Most pages have been migrated now!

For snapshot builds: Yes, https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#snapshot-builds, but they have to be actual SNAPSHOT builds. A mistake folks often make for these types of builds is the pom.xml <scm> <tag>, for snapshot builds you'll want to set it to the sha of the git commit.

Okay, cool. I’m away from keyboard today and most of tomorrow, playing backgammon in the country side with friends!

Nice! Enjoy!