Comments (7)
Yes, it should be relatively straightforward. Both Clojure and ClojureScript reader data could be merged before being passed to the writer. Ideally we'd also want some identifier to distinguish which functions are Clojure and ClojureScript.
from codox.
Thanks a lot for the prompt response! I'll aim then to try take a closer look at this in the next few weeks, and will update with a PR if I can figure out the details.
BTW, I'll note that I think that Codox still has a really important role to fulfil in the Clojure ecosystem. Projects like cljdoc are awesome, but (IMO) offer significantly different tradeoffs. I'm personally really happy that Codox is still around and kicking after so many years of service to the community 👍
Happy weekend, cheers! :-)
from codox.
Okay, took a quick look at this.
I propose the following:
- We add support for the
:language
value to be a set, e.g.#{:clojure :clojurescript}
. - If and only if >1 language is selected, we introduce new behaviour:
- The top-level index shall no longer contain namespace output, but only links to "Clojure" and "ClojureScript" sections.
[Figure A]
- Clicking "Clojure" or "ClojureScript" will now go to platform-specific index pages that contain namespace output.
[Figure B]
- The file structure includes "clojure" and "clojurescript" dirs.
[Figure C]
Figure A
Figure B
Figure C
Notes
- We don't try to intermingle the Clojure and ClojureScript documentation. I believe that would cause unnecessary noise and possible confusion - especially when different platforms may have different arguments and/or docstrings.
- We do NOT change the file structure or output unless >1 language is provided, meaning we don't break the URLs/links of any existing Codox users. Anyone using Codox for a single language won't see any change to their generated documentation.
@weavejester Does this appear reasonable to you, James?
If so, I'll prepare a PR when I get an opportunity.
Thanks again for your time + input. Cheers! :-)
from codox.
Update: have a potential implementation ready, see here for example output.
Notes
- Output is identical (unmodified) if
{:language :clojure}
or{:language :clojurescript}
. So will not break any pre-existing links. - If
{:language :both}
then:- The top-level index now hides "Namespaces", and instead shows "Platforms".
[Figure A]
- Language-level indexes are now present.
[Figure B]
- The top-level index now hides "Namespaces", and instead shows "Platforms".
- To simplify theming and prevent any theme/transform breaks, I've kept a flat file hierarchy.
[Figure C]
- I intentionally avoided intermingling Clojure and ClojureScript docs. I believe that causes unnecessary noise and possible confusion - especially when different platforms may have different arguments, docstrings, and/or namespaces.
[Figure A]
[Figure B]
[Figure C]
Next steps
Just let me know if you're happy with this approach and I'll prepare a PR. The code change is reasonable small and self-contained, I don't believe it should break any custom writers or themes, etc.
But zero pressure or urgency, I'm also quite happy to use a fork for this.
Thanks again! Cheers :-)
from codox.
Thanks for the detailed proposal!
I think the "Platforms" section could use a little adjustment. Previously you click a link on the sidebar, and it takes you to a specific page. There's only one thing selected. But in this case the user would be selecting two things, platform and namespace, or one thing, the index or some other documentation page.
One way to get around this is to treat the platform as a top-level folder, adding it above the namespace hierarchy. The problem with treating it as a folder is that I can see it being difficult to navigate for long hierarchies. For example:
- Clojure
- example
- core
- protocols
- readers
- edn
- json
- bson
- writers
- html
- markdown
- ClojureScript
Even if the ClojureScript folder is collapsed when accessing Clojure, and vice versa, you'd still need to scroll past all the Clojure namespaces to reach the ClojureScript part.
The alternative is to have it as a filter, similar to to how you've set it up, but we can make it more explicit by giving it a style that indicates it's a toggle.
Or perhaps a tab bar:
The tabs might be a better design language, as a user expects the view below a tab bar to change when they change tabs. With a toggle, the effect is more ambiguous.
What are your thoughts?
from codox.
Thanks for the detailed proposal!
You're very welcome, thanks for the quick + detailed response!
What are your thoughts?
In principle my ordered preferences would be:
- Tab bar
- Pill bar
- Current implementation
Language-nested namespace hierarchy
I'm not a fan of #4
(language-nested ns hierarchy), since part of my motivation in proposing to keep Clj and Cljs docs separate is the desire to reduce noise. For libraries like Timbre, there may be large ns hierarchies that are very different between platforms. And adding your point about possible deeply-nested hierarchies and potential issues like #211, I'd vote for avoiding that.
So that leaves #1-3
:
#3
seems the least invasive change.#1
seems conceptually the clearest, but might need the biggest layout change (it's not obvious to me where we'd put tabs in the current design).#2
seems like a decent middle-ground (I suspect we could squeeze the pills into a slightly enlarged header).
My 2c: #3
is probably sufficient if we want to keep things quick+easy. It feels okay in practice (demo), and it's ~ready to go.
Since #1-3
are all conceptually compatible (modal), we could also always do this in phases: i.e. first get the basic functionality in via #3
- then consider later work to improve the layout.
The important thing to get right at this point IMO would be the API, and the file/link structure - since that'd hurt to break later on.
I'm neutral on the layout, happy to go with your preference if you have something specific in mind 👍
BTW I've also added language labels to the var docs, with inline links to jump between languages when relevant:
In this screenshot: the "Clojure" var is selected. Clicking "Cljs" will jump to the same var in the ClojureScript namespace.
from codox.
Update: I'm experimenting with language selection in the header:
Still polishing a few things, I'll open a PR for your review once I'm happy with the design 👍
from codox.
Related Issues (20)
- boot-codox always output in some temporary directory HOT 1
- how do you document entire project (maybe put on Introduction html page?) HOT 1
- Crux and codox HOT 1
- Multiple projects that share the same root index.html HOT 3
- Document how to use with deps.edn HOT 5
- getting an error (0.10.7) HOT 2
- can't generate Clojurescript docs on re-frame template HOT 6
- codox crashes under Java 16 HOT 8
- Integrating Cloverage HOT 2
- In deps.edn projects, lookup qualified keywords in exec-args as aliases in basis HOT 4
- `:project` key in deps.edn is ignored. HOT 2
- CompilerException when macroexpanding an ns containing reader-condtional requires HOT 1
- How can I render the autogenerated codox docs as documentation in github ? HOT 2
- Could not transfer artifact com.vladsch.flexmark:flexmark-ext-emoji:jar:0.62.2
- Namespace trimming
- Cannot generate Source Links HOT 2
- Accept a basis for tools.build compatibility HOT 4
- jquery included in default theme has XSS vulnerability issue
- Regexes are not supported in EDN, and therefore not supported when Codox is used from tools.deps
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from codox.