Refine for cljdoc/codox

[lread]

Lemme know what you think. Details in commits.

Closes #28
(Does not include adding :keys destructuring to fn signatures as I felt these were noisy when reading docs on cljdoc, but you may want them still for other reasons).

To complete the story for cljdoc we'll also likely want to address #33 so that we can get our pom scm info correct.

[lread]

If you want to preview what docs will look like in cljdoc, you can try the following:

Terminal 1: launch a cljdoc server (leave this running)

docker pull cljdoc/cljdoc
mkdir -p /tmp/cljdoc
docker run --rm \
  --publish 8000:8000 \
  --volume "$HOME/.m2:/root/.m2" \
  --volume /tmp/cljdoc:/app/data \
  cljdoc/cljdoc

Terminal 2: import lib into cljdocs

clojure -X:jar
clojure -X:install
docker run --rm \
  --volume "$HOME/.m2:/root/.m2" \
  --volume /tmp/cljdoc:/app/data \
  --entrypoint clojure \
  cljdoc/cljdoc -M:cli ingest \
    --project com.phronemophobic/membrane.term \
    --version 0.9.0 \
    --git https://github.com/phronmophobic/membrane.term \
    --rev $(git rev-parse HEAD)

Browser: open http://localhost:8000/d/com.phronemophobic/membrane.term

Note: This preview does compensate for any broken pom scm.

Full cljdoc preview docs are here.

[phronmophobic]

(Does not include adding :keys destructuring to fn signatures as I felt these were noisy when reading docs on cljdoc, but you may want them still for other reasons).

I find the keys destructuring useful since it shows up as I type in my editor.
When I add the :keys, then it shows up like this rather than just run-term [opts]

I use the documentation in my editor much more than cljdoc so I'd prefer trying to get cljdoc to match my workflow than the other way around.

I don't have docker set up or another easy way to test how things look on cljdoc at the moment (but I'm working on it!). If :keys is noisy on cljdoc, is there a way to improve that on cljdoc's end? I'm always curious about others' workflows. Do other people not find that generally useful?

[phronmophobic]

This seems like it would be useful to make public.

[lread]

Yeah, good observation. I shall make it so.

[lread]

I decided to leave this one private and expose run-term and screenshots opts instead.
They both include default-color-scheme.

[phronmophobic]

I tend to lean more on the open side for these types of things, especially if they're just data. What's the reason for not making this public?

[lread]

My thinking:

• we are covered because it is included in both default-run-term-opts and default-screenshot-opts
• it is added to cljdoc docs, and thought it might be superfluous.

But... can easily expose it if that makes more sense to you. I have no strong feeling on the matter. If it will be useful to you or others, let's expose it.

[lread]

@phronmophobic lemme know your choice on this one, and I shall make it so.

[phronmophobic]

To me, it makes sense to expose it!

[lread]

Very good sir! It is done.

[lread]

re: :keys destructuring in fn signature: I might be focused too much on what looks pretty to me in cljdoc. I'll add in the destructuring.

[lread]

I don't have docker set up or another easy way to test how things look on cljdoc at the moment (but I'm working on it!). If :keys is noisy on cljdoc, is there a way to improve that on cljdoc's end? I'm always curious about others' workflows. Do other people not find that generally useful?

I think it might be a good hint if you remember what the values for the keys should be.
But my memory is not great, and I typically have to go to the docstring to get the details anyway.

[lread]

Ya I guess it doesn't look too bad in cljdoc:

[lread]

Ok @phronmophobic, took a shot at responding to your feedback, when you have time/interest, ready for next review.

[phronmophobic]

Cool. I'll take a look. Hopefully, these comments don't seem too nit-picky!

[lread]

Hopefully, these comments don't seem too nit-picky!

Nah, I'm cool. I really enjoy learning from the perspective of others.
All of your points seem like valid paths to me.
There are many right answers, but this is your library, so you should be happy with what goes into it!

[phronmophobic]

Everything looks good to me 👍 . I'll just wait on making default-color-scheme or I can make the change if that's easier. Thanks!

[lread]

Ok, ready for another review and potentially a merge!