Documentation in printable format (CSS media queries)

[SetTrend]

Synopsis

With this PR implemented, documentation becomes printable; i.e. without navigation, comment and other chrome.

Steps done

1. New SASS rules:
   1. All .interactive sections get hidden for printing.
   2. The contributors section gets hidden for printing.
   3. The .footer gets hidden for printing.
   4. The .page-links section gets hidden for printing.
2. I created a NodeJS script that recursively concatenates all MarkDown files within a folder into large "chapter" files. The new, automatically generated files match the regular expression: "(_\w+)?_all.md".

Further Information

At this time I have no clue on how to present the generated "*_all.md" files to the user. Perhaps you've got an idea?

[SetTrend]

@EugeneHlushko , @montogeek : Want to approve?

/ref: #2632

[EugeneHlushko]

Hi @SetTrend, we probably want to get rebuild into master first, let me catch up with @montogeek on this.

[EugeneHlushko]

Also i think we dont want to commit the aggregated files, rather build them before deploy

[SetTrend]

The aggregated files are important for printing, for the following reasons:

• I didn't add a TOC yet, but adding a TOC wouldn't make sense for 1-2 pages, each.

• Printing commonly is done in Brochure format, i.e. 2 sides per page:
  

  Printing each of the documentation's web pages separately would leave too many pages unnecessarily blank:
  

I suggest to add a "Print documentation" link to the documentation navigation pages

... which in turn would open the corresponding concatenated file and immediately open a printing dialog, i.e. calling window.print();.

Microsoft ASP.NET does the same (or similar):

I intentionally gave a calculated name to the concatenated files, so it would be quite easy to write a minor JavaScript for the click event of the corresponding anchor HTML element, calculating the concatenated file name from the current documentation page's file path:

btnHyperlinkPrintDocumentation.addEventHandler("click", () =>
{
  var newURL = `${(/^([/].+[/])[^/]+$/.exec(window.location.pathname.substring(docBasePath.length))[1] || "").replace("/","_")}_all.html`;

  window.open(newURL, newURL).focus().print();
});

[EugeneHlushko]

Yes files are important, but they can be generated on the fly before deployment from the fresh revision. We dont need to commit and ignore them.

UPD: The url for print is a must have when we merge this functionality 👍

[SetTrend]

Ah, sure, I now understand. So, you just don't want to have the "artifacts" stored in the repository. That's a great idea.

I can easily remove the files from my branch. However, I'm not too familiar with the WebPack build process. So, how would you suggest to go forward to have these available as HTML after build?

[EugeneHlushko]

I think what you did works well, its just the matter of when we generate the _*_all.md files. I suppose we will trigger it at some point before building html pages, but it will be trivial change since you already have made a script for it.

As we have changed the build setup in rebuild branch i'd like rebuild to get into master first before we introduce this change. There is last outstanding issue left and its almost done by @montogeek so rebuild should be merged into master very soon.

Meanwhile i suggest to remove the generated _*_all.md files from this branch and also remove the hooks from package.json as they are going to change when rebuild comes in and it will be easier to update your work with latest master at that future point.

[SetTrend]

I now removed the *_all.md files. I also catched-up with current master. Unfortunately something went wrong and all the master commits are listed now here. I don't know what went wrong and what I can do to revert my history to my original two commits.

I started a discussion at StackOverflow. If I won't get a remedy there, I'm going to delete my branch and re-create it. Do you perhaps have an idea what I can do to get my branch to only show the two commits originating from myself?

[EugeneHlushko]

Thats indeed weird but i don't seem to scratch an idea on top of my head for why it looks like this after merging master into it...

Good job on removing the stuff tho now it looks much better in the diff 👍

[SetTrend]

@EugeneHlushko:

Today, I edited the package.json file as requested.

I'm very sorry for the long delay. I'm doing this in my spare time and was busy with other projects. Plus, I needed to learn more about git in order to accomplish the clean-up.

Cheers,
Axel

/refs:

• How can I create merge requests after having updated my master branch?
• How can I inject an intermediate branch?
• How can I keep my Git history tidy even after rebasing/syncing in Visual Studio Code?
• Add "catch-up" sync option to Git extension

[EugeneHlushko]

For some reason this branch holds additional commit diff with master, lets have a look at it when we have rebuild merged into master. The worst case scenario we would cherry pick your stuff here and rebase on the updated master, therefore your contributions will be safe :)

reference: #2039

[EugeneHlushko]

Hi @SetTrend

I'm happy to confirm that rebuild finally was merged and we can proceed. Can you please update this branch and resolve conflicts? Or if its easier branch from master again and copy paste over your changes (if its quicker).

[SetTrend]

@EugeneHlushko:

I have now created a whole new fork and, after pulling the latest webpack.js.org master, I'm trying to apply my changes to the new version.

From what I can see, the HTML structure of the docs have changed. I need to apply @media print { display: none !important; } to these elements/classes:

header,
nav,
footer,
.notification-bar,
.page-links,
.gitter
{
  @media print {
    display: none !important;
  }}

(... plus a new one for the Contributors section).

From what I can see, server.jsx is the page root file. Where would you want me to put SCSS for that file (i.e. header, nav, footer)?

[EugeneHlushko]

I would suggest Site.scss under ./src/components/Site/Site.scss which imports footer, nav and header elements