News for hackers. Stuff that matters.
Re:Apple's DocC is excellent, but unusable for open source p... by KptMarchewa on Wednesday June 30, 2021 @05:39AM (#27686641)
Wait, what? What do they need it for?
Re:Apple's DocC is excellent, but unusable for open source p... by coldtea on Wednesday June 30, 2021 @07:29AM (#27687264)
Search? Interaction? Collapsable sections?

It's 2021.

Re:Apple's DocC is excellent, but unusable for open source p... by Zababa on Wednesday June 30, 2021 @02:27PM (#27691921)
Rust has all of them with vanilla JS. The code is clear and easy to understand, and could be reused by other people easily. Here's an example: https://doc.rust-lang.org/std/vec/struct.Vec.html
Re:Apple's DocC is excellent, but unusable for open source p... by ironmagma on Wednesday June 30, 2021 @02:37PM (#27692022)
There is no way anyone in their right mind would call main.js[1] easy to understand. It's basically complete chaos. Guillaume is making a good effort to clean up this inherited code slowly, but the interactions are still kind of broken and will be until this code is rewritten in a sane pattern such as MVU. FWIW, I have been working towards this for the past year.

[1] https://github.com/rust-lang/rust/blob/master/src/librustdoc...

Re:Apple's DocC is excellent, but unusable for open source p... by easrng on Wednesday June 30, 2021 @08:41PM (#27695170)
Looks easy to understand to me, it would be better if it was set up as modules instead of a single file full of IIFEs but it looks pretty good as is.
Re:Apple's DocC is excellent, but unusable for open source p... by Zababa on Wednesday June 30, 2021 @08:51PM (#27695233)
You're right, as a whole it's not trivial. I remember reading the search part and found it not particularly hard, but I missed the big picture. Thank you for your work!
Re:Apple's DocC is excellent, but unusable for open source p... by coldtea on Wednesday June 30, 2021 @04:59PM (#27693366)
>Rust has all of them with vanilla JS.

Which is neither here, nor there.

Since JS is required for those features (in the absense of a dynamic server backend), who cares whether it's bundled Vue.js or some hand-rolled vanilla JS?

I'm sure some care. I'm not sure many care, and I'm even less sure that they have any valid reason to care besides a knee-jerk "bloat" reaction.

Re:Apple's DocC is excellent, but unusable for open source p... by Zababa on Wednesday June 30, 2021 @08:50PM (#27695228)
If you look at the chain of comments, I'm saying that you can do with vanilla JS what you can do with Vue, so you don't "need" Vue. You're free to use it of course, but it's not "necessary". That was my main point.

> I'm even less sure that they have any valid reason to care besides a knee-jerk "bloat" reaction.

I totally agree! Especially if the team is already used to Vue or React or whatever and it will help them produce a higher quality product than going with something they don't know. I do value light software, but not to the point of stupid light [1], and not implementing feature because "Vue is bloat" would be an example of stupid light software.

[1]: https://www.arp242.net/stupid-light.html

Re:Apple's DocC is excellent, but unusable for open source p... by akiselev on Wednesday June 30, 2021 @05:39PM (#27693691)
There is a quantitative difference between a folder with some HTML + other assets and a project that requires a specific v8 runtime wrapper and its own build pipeline to generate the aforementioned artifacts.

My grandmother knows how to (and does) use the former. The latter guarantees I'll always have a job.

Re:Apple's DocC is excellent, but unusable for open source p... by coldtea on Wednesday June 30, 2021 @07:16PM (#27694655)
It's a documentation generation tool whose only goal target is official macOS development enviroment, on which all of this is handled automatically via the "compiler" bundled in XCode.

It's not some generic tool handed over for random projects to write their documentation on...

But even if it was, setting up a build pipeline is trivial for developers including grandmothers who code (it's not intended for their non-coders, whether they are grandmothers or not). Most teams already have similar pipelines for their documentation anyway, whether it bundles JS or not, and are already processing it with Node (e.g. JSDoc), Python (e.g. Sphinx), Java equivalents, and so on.

Re:Apple's DocC is excellent, but unusable for open source p... by Klonoar on Wednesday June 30, 2021 @11:48AM (#27689946)
None of these require a framework.
Re:Apple's DocC is excellent, but unusable for open source p... by coldtea on Thursday July 01, 2021 @03:11AM (#27697011)
We don't use frameworks because they're required, we use them because they make dev lives easier and provide some common ready-made structure and functionality.

Strictly speaking, nothing ever requires a framework: after all, any framework is just code - and you could always write vanilla code to achieve the same functionality (up to re-implementing the whole code of the framework yourself from scratch).

Re:Apple's DocC is excellent, but unusable for open source p... by Klonoar on Thursday July 01, 2021 @02:22PM (#27702518)
This comment does nothing except state the obvious. ;P

The parent I'm responding to listed very simple examples that in no way necessitate a framework; of course frameworks can be useful for larger scaffolding and the like.

Where exactly do you think you're commenting...?

Re:Apple's DocC is excellent, but unusable for open source p... by est31 on Wednesday June 30, 2021 @03:28PM (#27692534)
collapsible sections are possible using css only, or using the details tag (not even css needed). As for search, you don't need a framework for that.
Re:Apple's DocC is excellent, but unusable for open source p... by Andrew_nenakhov on Wednesday June 30, 2021 @05:48AM (#27686683)
To a boy with a hammer everything looks like a nail, I guess.
Re:Apple's DocC is excellent, but unusable for open source p... by planb on Wednesday June 30, 2021 @05:55AM (#27686716)
Interactive Tutorials? https://developer.apple.com/documentation/docc/building-an-i...

I found that via web search, but I couldn't find a demo anywhere online...

Re:Apple's DocC is excellent, but unusable for open source p... by pornel on Wednesday June 30, 2021 @06:02AM (#27686756)
The tutorials are written manually in a SwiftUI-like script. It's a totally different thing from the docs auto-generator.
Re:Apple's DocC is excellent, but unusable for open source p... by planb on Wednesday June 30, 2021 @07:33AM (#27687284)
Thanks for clarifying, but are you sure? On the very page I mentioned, there's a link at the bottom: "Distributing Documentation to External Developers" and on that page it says: "Share your documentation directly with Xcode users or host it on a web server."

Sounds to me like you build that documentation using the SwiftUI-like DSL, but it is distributed in the DocC package.