phronmophobic / membrane.term

A terminal emulator in pure clojure
Eclipse Public License 1.0
58 stars 1 forks source link

Refine for cljdoc/codox #34

Closed lread closed 2 years ago

lread commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

(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] Screen Shot 2021-12-01 at 11 37 04 AM

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?

lread commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

image

lread commented 2 years ago

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

phronmophobic commented 2 years ago

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

lread commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

Ok, ready for another review and potentially a merge!