Generate PDF or better HTML

[sanguish]

The post WWDC 2014 documentation format with expanding items and other features is extremely difficult to read offline. And printing is an absolute nightmare.

While I understand the want to fit in with the existing documentation format, perhaps it's best to find out what developers need, rather than what a team of artists and tools engineers decided was what things should look like.

Printable doc is essentially gone from all of Apple's distributed documentation. While that is perhaps helpful for some, it makes reading it in many cases difficult.

Anyways, a suggestion from someone who worked in Developer Publications at Apple for 12 years till last February. :)

[segiddins]

@sanguish we also support generating dash docsets for offline use. If the styling doesn't serve your needs, you can pass in custom templates.

[jpsim]

While I understand the want to fit in with the existing documentation format, perhaps it's best to find out what developers need, rather than what a team of artists and tools engineers decided was what things should look like.

Thanks for the suggestion! I'd say the main reason the generated output looks the way it does is that I'm a shitty front-end web designer! We've been luck to get a handful of PRs from jazzy users over time that improves the generated HTML and CSS, and more improvements are certainly welcome!

Jazzy also supports using custom mustache templates & sass files, so I'd love for webdesign-savvy jazzy users to contribute more themes that end users could choose from. Again, kind of outside my wheelhouse.

[sanguish]

@jpsim lI think you're being too hard on yourself. Most of these types of tools do generate Apple style docs. The problem is that Apple's current doc style just sucks.

@segiddins By offline use, I meant paper... :-)

And I suck at templates too. :-)

[agentk]

I've simplified the styling a fair bit for ReduxKit API docs so that it now works on mobile. Removed all fixed and absolute positioning and replaced it with a flexbox. It's probably a bit more bleeding edge than most people are comfortable with, but it adapts well to printing and PDF.

Feel free to reuse as much as you like from http://reduxkit.github.io/ReduxKit/api/ & https://github.com/ReduxKit/ReduxKit/tree/gh-pages.

[pcantrell]

Nice work @agentk. At a very quick glance, looks like this CSS has some big improvements. (Also, interesting lib!) We should consider adopting some of this.

Jazzy’s existing positioning rules cause all sorts of weird scrolling bugs when the nav on the left is taller than the window, so just removing them is a big improvement.

[jpsim]

Yes, very nice work! 👏 please do consider contributing some of those improvements back to jazzy!

[agentk]

Is it possible to contribute multiple themes that can be selected from? Or maybe even a contrib dir for asset + template collections? The CSS and template changes I've made are definitely not for everyone, considering it's limited to IE10+ (after autoprefixing).

[jpsim]

Is it possible to contribute multiple themes that can be selected from? Or maybe even a contrib dir for asset + template collections? The CSS and template changes I've made are definitely not for everyone, considering it's limited to IE10+ (after autoprefixing).

Absolutely! There's no real infrastructure in place for user-selectable "themes" at the moment because we only have the one! If you wanted to help with this, without investing the time to build out the theme infrastructure, you could just make a PR towards jazzy with the templates, therefore contributing them to the project under the jazzy license, and I could take it from there to provide it via a "theme" configuration option.

The one requirement I have is that you have to pick a cool name for it! 😎

[agentk]

Sweet. I've created a /themes/ folder in #436 with the default and simplified themes. I've just coped the default assets and templates into the jazzy theme. So they are in both places at the moment. Don't feel beholden to the name or location of the themes. Just wanted to get it started and contributed.

P.S. The simplified theme fits in well with #435 for extra documentation added to the sidebar. I could use a lot of guidance on that contribution though. I'll submit the PR to get it documented, but I would recommend rejecting and reworking it.

[agentk]

@sanguish The fullwidth theme should get you pretty close now. I can see I've missed removing the sidebar from the print view though. Other than that, is there anything else you would suggest to make it more printable?

[jpsim]

@sanguish sorry for not commenting here for a while. Have you looked at how the full width theme fares when printed? If you can identify specific areas of improvement, I'm happy to keep this open to motivate myself and other contributors to make it better!

[jpsim]

Closing since I believe some improvements were made in this area since this issue was filed.