GSoD2020 new Interactive Book structure #474

danielluehr · 2020-10-07T12:58:58Z

This PR includes the proposed new structure of the book.

All chapters (directories) and sections (md files in each chapter directory) contain only minimal content:

Front matter
Main heading
Chapter TOC (pointing to sections, generated automatically using jeckyll's liquid and JTD structure)
Section TOC code ("internal" jekyll/JTD processing)

Also, a new utility directory was created. It includes a python script which can generate the chapter and sections directory and files from a chapter template written in yaml (examples are included). It also include some helper emacs' lisp code to use org-mode source files to generate the MD files. Org sources can also be created using the python script.

chapter creation script
chapter template yaml file
example yaml files (used to populate the new proposed structure of the book)
org-mode helper lisp code

Also, with extra plugins.

Error occurred when yaml chapter description does not include all levels (basic, medium, advanced)

Also, add missing .no_toc property for the Table of contents header.

hound · 2020-10-07T12:59:04Z

assets/css/just-the-docs-circuitversedark.scss

@@ -0,0 +1,3 @@
+---
+---
+{% include css/just-the-docs.scss.liquid color_scheme="circuitversedark" %}


Invalid CSS after "...uitversedark" %": expected "{", was "}"

hound · 2020-10-07T12:59:05Z

assets/css/just-the-docs-circuitverse.scss

@@ -0,0 +1,3 @@
+---
+---
+{% include css/just-the-docs.scss.liquid color_scheme="circuitverse" %}


Invalid CSS after "...circuitverse" %": expected "{", was "}"

hound · 2020-10-07T12:59:05Z

_sass/custom/custom.scss

+	    display: inline;
+	}
+	&.active {
+	    list-style: disc url('/assets/images/nav-marker-active.svg') inside;


Prefer double-quoted strings

hound · 2020-10-07T12:59:05Z

_sass/custom/custom.scss

+    .nav-list-item {
+	.nav-list-link{
+	    display: inline;
+	}


Rule declaration should be followed by an empty line

hound · 2020-10-07T12:59:06Z

_sass/custom/custom.scss

+    list-style: circle url('/assets/images/nav-marker-inactive.svg') inside;
+
+    .nav-list-item {
+	.nav-list-link{


Opening curly brace { should be preceded by one space
Selector should have depth of applicability no greater than 2, but was 3

hound · 2020-10-07T12:59:07Z

_sass/custom/custom.scss

+
+.main {
+  @include mq(md) {
+    position: relative;


Properties should be ordered margin-left, max-width, position

hound · 2020-10-07T12:59:07Z

_sass/custom/custom.scss

+    min-width: $nav-width;
+  }
+  &.active {
+      display: none;


Line should be indented 4 spaces, but was indented 6 spaces

hound · 2020-10-07T12:59:07Z

_sass/custom/custom.scss

+  @include mq(lg) {
+    width: calc((100% - #{$nav-width + $content-width}) / 4 + #{$nav-width});
+    min-width: $nav-width;
+  }


@include declaration should be followed by an empty line

hound · 2020-10-07T12:59:08Z

_sass/custom/custom.scss

+  }
+
+  @include mq(lg) {
+    width: calc((100% - #{$nav-width + $content-width}) / 4 + #{$nav-width});


Properties should be ordered min-width, width

hound · 2020-10-07T12:59:08Z

_sass/custom/custom.scss

+  background-color: $sidebar-color;
+
+  @include mq(md) {
+    flex-wrap: nowrap;


Properties should be ordered align-items, border-right, flex-direction, flex-wrap, height, position, width

Shivansh2407

@danielluehr the changes look good to me. Nice work done 👍 .

Some Things that need to be fixed :

The Alignment of Headings in Sidebar with down arrow and without down arrow is different.
The Edit on CircuitVerse currently is shown at the Bottom, shouldn't it be the same as shown in the top right as a button. Let me know your views.
The Conflicting files needs to fixed. I guess this has happened because Daniel has not pulled from the Master again after the first PR got merged in GSOD2020 branch.
The previous and the next buttons have been removed. Any specific reasons?

For all the above things mentioned, we can open up new issues and put them in the slack channel so that the new/existing contributors can help us with this. This way Daniel can focus more on the Documentation work and creating New content for the Book 📖

@satu0king Please have a look and let me know your views

Shivansh2407 · 2020-10-07T13:55:05Z

docs/binary-algebra/ieee-std-754.md

+has_children: false
+---
+
+# IEEE Standar 754


Typo fix: Standard

Same goes for utils/chapters/ch_binary_algebra.yml : Line 35

Hi,

Sorry for creating the conflicts... I was so anxious to upload the changes that I forgot to merge upstream first...

I am submitting a new PR with the merge conflicts solved (I hope). Also, it includes the fix for the "Standard" typo.

Regarding the other comments I just want to provide complementary information:

The current version (pre-GSoD2020) didn't use 2-level (i.e. chapters and sections), maybe it wasn't implemented in JTD at the time, but now it is a feature of JTD, but it needs proper styling in the navbar. Also the sections in the chapter (when the navbar is expanded) don't seem to have a consistent style (they are plain gray). It is the same in the current version (check the Flip-flops page and sub-pages, for an example). I will open an issue so anyone available and interested in fixing the styling can work on it.

I kept the "original" JTD "edit on github" link (which goes at the bottom) and added a link to the github repository on top. The idea is to stop breaking things with the upstream JTD Gem. In any case the links at the top need to get proper styling.
However, if you want to move the edit on github button to the top, I would recommend it to go in the same button bar as the sidebar button, and the code can be put in the corresponding include file.

(already mentioned above)

The Prev/Next buttons liquid code started failing with the current JTD theme. I haven't investigated the reason. And it completely failed (jekyll wouldn't generate the site) when I added the full new structure (with chapters and sections). I will also open an issue so someone can start working on it and fix the prev/next navigation buttons.

Thanks!

…words.

# Conflicts: # README.md # _config.yml # _includes/content_header.html # docs/binary-algebra/index.md # docs/binary-representation/index.md

It probably should go inside an "About" chapter together with other misc sections.

Shivansh2407

Working Well @danielluehr 🎉. I agree with you that we can open issues for the GSOD 2020 branch so that other contributors can also fix them while you can focus on content creation.
#475 and #476 were opened earlier.
Another possible issue is, when the sidebar button is clicked all the elements get shifted to left, while only the breadcrumb navigation element remains there. This should also sync with other elements when shifting to the left is what I think. let me know your views.
@satu0king please review this and merge accordingly 👍

danielluehr · 2020-10-13T10:24:10Z

Working Well @danielluehr tada. I agree with you that we can open issues for the GSOD 2020 branch so that other contributors can also fix them while you can focus on content creation.
#475 and #476 were opened earlier.
Another possible issue is, when the sidebar button is clicked all the elements get shifted to left, while only the breadcrumb navigation element remains there. This should also sync with other elements when shifting to the left is what I think. let me know your views.
@satu0king please review this and merge accordingly +1

About the sidebar alignment, you are right. I just copied the positioning calculations from the previous style to the new one and I think it needs double checking. Also, the breadcrumb was not used in the previous design, so its positioning was not updated, I think it is safe to style it accordingly and later it can be decided whether to keep or not the breadcrumbs.

Thanks!

danielluehr added 24 commits September 29, 2020 16:55

Remove files from previous version.

e291380

"Fresh" jekyll site with (almost) CV look'n'feel.

a4c39b6

Also, with extra plugins.

Empty index.md for each "chapter".

bf6c81e

Add favicon.

bd2b1c0

python utility to create chapter skeleton from a yml file.

7c1add1

example chapter yaml file.

c9fca86

updated order string in chapter creation utility.

2f81b01

Fix bug in chapter creation utility.

0fe5ef3

Error occurred when yaml chapter description does not include all levels (basic, medium, advanced)

jekyll include file to automaticaly generate chapter toc.

5fb0395

empty chapter template (replaces chapter example yaml).

dcf7ae6

New structure's chapter definitions.

45c6c22

New structure generated from yaml files.

a3488a3

Add has_toc: false property to disable JTD auto chapter toc.

7b9a4b7

Fix include for automatic chapter generation.

85c7128

Remove jekyll's sample pages

c02fce3

exclude utils directory from jekyll processing.

1ba9aa9

Copy CV's original index README and CODE_OF_CONDUCT files.

9f9b017

first draft of contribution_guidelines.

fc567bb

Comment out Prev/Next buttons code since it is not currently working.

1290a83

chapter creation utility now process chapter order.

91f18d5

Also, add missing .no_toc property for the Table of contents header.

New chapter definition yaml files including chapter order.

169e301

Update content with chapter order and no_toc property for TOC header.

082a301

Orgmode lisp utility to extend ox-gfm to export jekyll+JTD MD.

7efbbe9

Contributing guidelines source in org-mode.

d1f270f

hound bot reviewed Oct 7, 2020

View reviewed changes

Shivansh2407 requested changes Oct 7, 2020

View reviewed changes

danielluehr added 4 commits October 7, 2020 14:29

Move previous section of binary numbers into new sections.

9fcd504

Interactive block in binary numbers section.

d2b367d

Org-mode sources and generating yaml templates.

032da48

Improve the org-mode helper lisp code to allow bold in the middle of …

345924e

…words.

danielluehr added 5 commits October 7, 2020 15:10

Merge remote-tracking branch 'upstream/GSoD2020' into GSoD2020

39eb8d3

# Conflicts: # README.md # _config.yml # _includes/content_header.html # docs/binary-algebra/index.md # docs/binary-representation/index.md

Restoring files lost during the merge conflict resolution.

c6ac344

Fix typo in IEEE Standar(d) heading.

d930274

Replaced JTD repo with CV repo for edit on github link.

dda8fc0

Move contributing_guidelines to the end of the book (in the meantime).

c4402ef

It probably should go inside an "About" chapter together with other misc sections.

This was referenced Oct 7, 2020

CSS styles for the new version (GSoD2020) of the Interactive Book #475

Closed

Broken Prev/Next navigation buttons with new just-the-doc theme and new structure (GSoD2020) #476

Closed

Shivansh2407 approved these changes Oct 13, 2020

View reviewed changes

satu0king merged commit 6aa8c98 into CircuitVerse:GSoD2020 Oct 14, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GSoD2020 new Interactive Book structure #474

GSoD2020 new Interactive Book structure #474

danielluehr commented Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

hound bot Oct 7, 2020

Shivansh2407 left a comment

Shivansh2407 Oct 7, 2020

Shivansh2407 Oct 7, 2020

danielluehr Oct 7, 2020

Shivansh2407 left a comment

danielluehr commented Oct 13, 2020

GSoD2020 new Interactive Book structure #474

GSoD2020 new Interactive Book structure #474

Conversation

danielluehr commented Oct 7, 2020

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

hound bot Oct 7, 2020

Choose a reason for hiding this comment

Shivansh2407 left a comment

Choose a reason for hiding this comment

Shivansh2407 Oct 7, 2020

Choose a reason for hiding this comment

Shivansh2407 Oct 7, 2020

Choose a reason for hiding this comment

danielluehr Oct 7, 2020

Choose a reason for hiding this comment

Shivansh2407 left a comment

Choose a reason for hiding this comment

danielluehr commented Oct 13, 2020