Use cljdoc for the poly tool documentation #318
Comments
This was referenced Oct 18, 2023
This was referenced Nov 11, 2023
tengstrand
pushed a commit
that referenced
this issue
Nov 21, 2023
* Review and update Configuration doc Introduce user and poly config as separate categories. Include filename in section headings. Group all deps.edn config section headings under a new section heading. Explain how each config file is initially created and how it is changed. Clearly mark derived configuration. Show default config values when appropriate. Add note that output in doc might not always match output if following along in tutorial (for illustrative purposes). That said, update output to better match actual output. Ensure that `:key-names` do not wrap in tables. Link to other docs when helpful. Fix some typos. Edits for clarity. * review feedback: fix typos issue #318
tengstrand
added a commit
that referenced
this issue
Nov 22, 2023
* Libraries doc: small tweak (#394) Use less words. Don't assume poly shell. * Fixd a minor "typo". * Changed from warning to error in error 111. * Changed from Warning 206 to Error 111 in various places. * Updated version information. * Review and update Configuration doc (#395) * Review and update Configuration doc Introduce user and poly config as separate categories. Include filename in section headings. Group all deps.edn config section headings under a new section heading. Explain how each config file is initially created and how it is changed. Clearly mark derived configuration. Show default config values when appropriate. Add note that output in doc might not always match output if following along in tutorial (for illustrative purposes). That said, update output to better match actual output. Ensure that `:key-names` do not wrap in tables. Link to other docs when helpful. Fix some typos. Edits for clarity. * review feedback: fix typos issue #318 * Added :project-lib-deps key to the projects section. * Snapshot #17. --------- Authored-by: Lee Read <[email protected]>
tengstrand
pushed a commit
that referenced
this issue
Nov 23, 2023
issue #318 Add a section for Libraries and a sub-section for caveats when publishing multiple libraries. Turf the paragraph on the advantages of multiple libraries. I felt it was a stretch and wishful thinking, something that readers would see through and won't appreciate. Add more links to other docs. Edits for clarity.
tengstrand
pushed a commit
that referenced
this issue
Nov 23, 2023
issue #318 Add a suggestion to consider using the poly shell. Minor edits.
tengstrand
pushed a commit
that referenced
this issue
Nov 24, 2023
issue #318 * Update :poly alias for create_example script Noticed that examples/doc-example/deps.edn :poly alias was stale, so updated sections sources appropriately. While doing so noticed that create example work for polyx no longer needs a custom deps.edn so turfed it. * Review and Update Explore the Workspace doc Add sections and toc. Warn about backward compatibility and link to Versions for changelog. Add content on ws-dir argument (which was originally in dependencies.adoc but did not make sense there). Edits for clarity.
tengstrand
pushed a commit
that referenced
this issue
Nov 24, 2023
issue #318 * Review and Update Source Code doc Added table of contents. The first block of text talks specifically about multiple paths but had no heading, so added one. I downplayed .clj vs .cljc code organization in first section to be an illustrative of multiple paths. (To me, the text seemed to be recommending separate `clj` and `cljc` dirs was some sort of poly recommendation, which felt odd.) Reworded a some text under the frontend section. The term "stripped" did not mean much to me, so I tried to instead explain. The term "import" was problematic because it will be confused with Clojure's `import` so reworded that too. Other edits for clarity. * review feedback: monolith -> monorepo
Merged
tengstrand
added a commit
that referenced
this issue
Nov 24, 2023
* Moved bookmark from :outdated to :update. * Review and update Artifacts doc (#399) issue #318 Add a section for Libraries and a sub-section for caveats when publishing multiple libraries. Turf the paragraph on the advantages of multiple libraries. I felt it was a stretch and wishful thinking, something that readers would see through and won't appreciate. Add more links to other docs. Edits for clarity. * Review and update Clojure CLI Tool doc (#401) issue #318 Add a suggestion to consider using the poly shell. Minor edits. * Review and Update Explore the Workspace doc (#400) issue #318 * Update :poly alias for create_example script Noticed that examples/doc-example/deps.edn :poly alias was stale, so updated sections sources appropriately. While doing so noticed that create example work for polyx no longer needs a custom deps.edn so turfed it. * Review and Update Explore the Workspace doc Add sections and toc. Warn about backward compatibility and link to Versions for changelog. Add content on ws-dir argument (which was originally in dependencies.adoc but did not make sense there). Edits for clarity. * Review and Update Source Code doc (#398) issue #318 * Review and Update Source Code doc Added table of contents. The first block of text talks specifically about multiple paths but had no heading, so added one. I downplayed .clj vs .cljc code organization in first section to be an illustrative of multiple paths. (To me, the text seemed to be recommending separate `clj` and `cljc` dirs was some sort of poly recommendation, which felt odd.) Reworded a some text under the frontend section. The term "stripped" did not mean much to me, so I tried to instead explain. The term "import" was problematic because it will be confused with Clojure's `import` so reworded that too. Other edits for clarity. * review feedback: monolith -> monorepo * Snapshot #18 --------- Authored-by: Lee Read <[email protected]>
tengstrand
pushed a commit
that referenced
this issue
Nov 25, 2023
issue #318 Joakim surveyed the community and they responded that they are good with removing using `poly` as a Clojure Tool. Seems like a good idea, the mismatch between argument parsing was awkward and just one more thing to learn. This change reflects docs only and does not remove supporting code. Also: noticed and turfed an old println used for debugging in create_example.clj
tengstrand
pushed a commit
that referenced
this issue
Nov 25, 2023
issue #318 * Review and update Validations doc Re-organize and re-section. Add some info on exit codes. Add a screenshot to show an example of `ws get:messages`. Update Warning 206 screenshot to what it should be now: Error 111. Turf note on Warning 207 that it is only be applied to check command, it's not true anymore. Configuration doc: - the only reason we documented `:bricks` was to describe disabling Error 111, this is no longer a feature so we no longer need to describe `:bricks`. - correct description for `:necessary` and add link to Validations doc. Edits for clarity. * review feeback: describe :keep-lib-versions * :bricks - add default value for consistency
tengstrand
pushed a commit
that referenced
this issue
Nov 25, 2023
issue #318 Add sections and toc. Move note and caution to top of doc. Optimize flow and add some images on how to get the sha from GitHub. Explain how to get shas using git from command line. Turf code block with ANSI escape codes and explain in text instead. Link to Systems docs for overview image examples. Edits for clarity.
tengstrand
pushed a commit
that referenced
this issue
Nov 25, 2023
issue #318 Add a quote on naming. Add links to other docs. Naming is subjective. Change tone from "this is a good way to name" to "consider naming like so". Reorder advice on multiple interfaces with same name to come after more generic advice on components. "For tools, we can use the tool name" did not give any naming advice at all, so replaced it with a suggestion. Edits for clarity.
Merged
tengstrand
added a commit
that referenced
this issue
Nov 25, 2023
issue #318 * Turf docs on Clojure Tools CLI Usage (#405) Joakim surveyed the community and they responded that they are good with removing using `poly` as a Clojure Tool. Seems like a good idea, the mismatch between argument parsing was awkward and just one more thing to learn. This change reflects docs only and does not remove supporting code. Also: noticed and turfed an old println used for debugging in create_example.clj * Review and update Validations doc (#404) issue #318 * Review and update Validations doc Re-organize and re-section. Add some info on exit codes. Add a screenshot to show an example of `ws get:messages`. Update Warning 206 screenshot to what it should be now: Error 111. Turf note on Warning 207 that it is only be applied to check command, it's not true anymore. Configuration doc: - the only reason we documented `:bricks` was to describe disabling Error 111, this is no longer a feature so we no longer need to describe `:bricks`. - correct description for `:necessary` and add link to Validations doc. Edits for clarity. * review feeback: describe :keep-lib-versions * :bricks - add default value for consistency * Review and Update Polyx doc (#406) issue #318 Add sections and toc. Move note and caution to top of doc. Optimize flow and add some images on how to get the sha from GitHub. Explain how to get shas using git from command line. Turf code block with ANSI escape codes and explain in text instead. Link to Systems docs for overview image examples. Edits for clarity. * Review and Update Naming doc (#407) issue #318 Add a quote on naming. Add links to other docs. Naming is subjective. Change tone from "this is a good way to name" to "consider naming like so". Reorder advice on multiple interfaces with same name to come after more generic advice on components. "For tools, we can use the tool name" did not give any naming advice at all, so replaced it with a suggestion. Edits for clarity. * Drop support for Clojure CLI Tool syntax. Snapshot #19. --------- Co-authored-by: Lee Read <[email protected]>
tengstrand
pushed a commit
that referenced
this issue
Nov 26, 2023
issue #318 * Review and Update Git Hook doc Some folks find git hooks more of a nuisance than a help, so I downplayed them to make them feel like an option rather than a recommendation. Example hook now uses the `:poly` alias for a simpler script that can be copy pasted. Mention example hook script is OS-specific. Add some warnings and tips. Link to other docs. Edits for clarity. * review feedback: clarify tip
tengstrand
pushed a commit
that referenced
this issue
Nov 26, 2023
issue #318 I shared with Joakim that I found this doc confusing because it does not talk about polylith at all. It is geared toward object oriented developers coming to Clojure and what that means in an IDE. He asked the polylith community what they thought and they agreed the doc could be deleted. Note: when deleting `context` from `doc :page` output example, I went from 2 cols to 3. I thought this was a better use of vertical space.
tengstrand
pushed a commit
that referenced
this issue
Nov 27, 2023
issue #318 Add toc and a section. Show colors first. Give examples for what colors are used for. Include ANSI color codes (and names where they differ) to give readers more of chance to be able to configure for their terminal. Explain that sample colors represent a terminal config that the poly developers like (before these seemed to be showing the absolute colors poly would emit, which is not the case). Verify sample RGB colors and regenerate images with ImageMagick in `polylith.clj.core.util.interface.color` via temporary code: ```clojure (comment (require '[clojure.java.shell :as shell]) (run! (fn [[color [r g b]]] (let [hex-color (format "#%02x%02x%02x" r g b)] (println color hex-color) (shell/sh "convert" "-size" "38x38" (format "canvas:%s" hex-color) (format "doc/images/colors/%s.png" (name color))))) colors) nil) ``` Correct filename tyo: yelow.png -> yellow.png No longer mislead about the power of `dark` and `light`. They have very little effect and are minor tweaks for terminal color theme configuration. Polyx: mention that images always use a dark-themed output. Edits for clarity.
tengstrand
pushed a commit
that referenced
this issue
Nov 29, 2023
issue #318 * Review and Update Developing Poly doc Re-order and re-section some content for an easier to follow flow. Add a Contributing section. Currently my (@lread) preferences and biases, polylith core team can adapt to their point of view. Add a few more details on cljdoc. Give concrete example of using other workspace usage. Edits for clarity. * Address review feeback Fix typos. Contributing: describe next-release.txt. Note that adoc kbd macros should be used.
tengstrand
pushed a commit
that referenced
this issue
Dec 7, 2023
issue #318 After me discussing with Joakim and then he with Sean, we found that tracking per project did not make sense. So it that content has been turfed. Described 2 simple tagging/release strategies for readers to consider.
Merged
tengstrand
added a commit
that referenced
this issue
Dec 8, 2023
* Drop support for Clojure CLI Tool syntax. * Added link to deps.edn Reference. * Review and Update Git Hook doc (#409) issue #318 * Review and Update Git Hook doc Some folks find git hooks more of a nuisance than a help, so I downplayed them to make them feel like an option rather than a recommendation. Example hook now uses the `:poly` alias for a simpler script that can be copy pasted. Mention example hook script is OS-specific. Add some warnings and tips. Link to other docs. Edits for clarity. * review feedback: clarify tip * Turf Context doc (#410) issue #318 I shared with Joakim that I found this doc confusing because it does not talk about polylith at all. It is geared toward object oriented developers coming to Clojure and what that means in an IDE. He asked the polylith community what they thought and they agreed the doc could be deleted. Note: when deleting `context` from `doc :page` output example, I went from 2 cols to 3. I thought this was a better use of vertical space. * Review and update Colors doc (#411) issue #318 Add toc and a section. Show colors first. Give examples for what colors are used for. Include ANSI color codes (and names where they differ) to give readers more of chance to be able to configure for their terminal. Explain that sample colors represent a terminal config that the poly developers like (before these seemed to be showing the absolute colors poly would emit, which is not the case). Verify sample RGB colors and regenerate images with ImageMagick in `polylith.clj.core.util.interface.color` via temporary code: ```clojure (comment (require '[clojure.java.shell :as shell]) (run! (fn [[color [r g b]]] (let [hex-color (format "#%02x%02x%02x" r g b)] (println color hex-color) (shell/sh "convert" "-size" "38x38" (format "canvas:%s" hex-color) (format "doc/images/colors/%s.png" (name color))))) colors) nil) ``` Correct filename tyo: yelow.png -> yellow.png No longer mislead about the power of `dark` and `light`. They have very little effect and are minor tweaks for terminal color theme configuration. Polyx: mention that images always use a dark-themed output. Edits for clarity. * Review and Update Developing Poly doc (#412) issue #318 * Review and Update Developing Poly doc Re-order and re-section some content for an easier to follow flow. Add a Contributing section. Currently my (@lread) preferences and biases, polylith core team can adapt to their point of view. Add a few more details on cljdoc. Give concrete example of using other workspace usage. Edits for clarity. * Address review feeback Fix typos. Contributing: describe next-release.txt. Note that adoc kbd macros should be used. * Review and update Continuous Integration doc (#413) issue #318 After me discussing with Joakim and then he with Sean, we found that tracking per project did not make sense. So it that content has been turfed. Described 2 simple tagging/release strategies for readers to consider. * Support :swap-axes for the deps command, as a way to swap the x and y axes. * Fixed typo in test. --------- Co-authored-by: Lee Read <[email protected]> Co-authored-by: Joakim Tengstrand <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Today we use GitBook for the poly tool documentation. The main drawback is that it lives in a separate repository which makes it hard to keep the code and the documentation in sync. Investigate if cljdoc can be used instead, which allows us to store the documentation together with the source code.
The text was updated successfully, but these errors were encountered: