New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New documentation structure: ch. Introduction #294

Merged
merged 5 commits into from Feb 22, 2017

Conversation

Projects
None yet
2 participants
@1138-4EB
Contributor

1138-4EB commented Feb 21, 2017

Related to #280, note that the PR targets branch new-documentation-structure, not master.

I believe the first chapter is ready for you to review and give feedback: http://ghdl-devfork.readthedocs.io/en/new-documentation-structure/

1138-4EB added some commits Feb 19, 2017

Allow markdown
Last files from oldmds removed. All the content is in the new structure now. COPYING replaced with the md version.

Update NEWS.md
README.md, index, WhatIsVHDL, WhatIsGHDL ready for review.
Add shortcuts for shields in a single file and include it where used.
Create base64 GitHub and Travis-CI logos with b64.io and add them to self-created shields. Replace gitter with shield.io's variant.
Start rewriting <Contributing>

@1138-4EB 1138-4EB force-pushed the 1138-4EB:new-documentation-structure branch 6 times, most recently from f5efa79 to 7a1ded0 Feb 21, 2017

@1138-4EB

This comment has been minimized.

Contributor

1138-4EB commented Feb 21, 2017

The latest update fixes the sidebar for small screens (mobile devices). It also hides redundant info in the 'version' tab on the bottom-left. It reduces the font size slightly, and specially in the footer, where margins are also reduced. All of it is done with CSS, on top of the default RTD theme, through a file which I named theme_overrides.css.

@1138-4EB 1138-4EB force-pushed the 1138-4EB:new-documentation-structure branch from 7a1ded0 to b3fcbf3 Feb 22, 2017

@Paebbels Paebbels self-requested a review Feb 22, 2017

@Paebbels Paebbels self-assigned this Feb 22, 2017

@1138-4EB 1138-4EB force-pushed the 1138-4EB:new-documentation-structure branch 3 times, most recently from 0dc4420 to c49f7f4 Feb 22, 2017

@Paebbels

This comment has been minimized.

Member

Paebbels commented Feb 22, 2017

Questions:

  • Why is the documentation content centered?
    It looks strange on big screens.
  • Why are selected navigation bar items indented?
    That suggests a sub-level which does not exist.
  • Do we want to use justified text in stead of ragged right?
    The PoC documentation contains such a style fix.
  • Page "About GHDL"
    • I would't write VHDL and GHDl every time in italic. Italic is usually used to introduce a term or wording. So italic is used the first time a word or wording appears, but not repeated.
    • directive include is broken (visible in text), thus |trade| doesn't work.
    • GHW points to a local GHDL parameter, whereas VCD points to wikipedia. (you can create an external link syntax for the English wikipedia if you like.)
    • Who uses GHDL:
      • PoC - A Vendor-Independent, Open-Source IP Core and Utility Library.
        [GitHub shield] [RTD shield]
      • VUnit -
        [GitHub shield] [RTD shield]
      • IEEE P1076 WG -
        [GitLab shield]
  • Page "Contributing"
    • I wouldn't use shields in the text. That's not the purpose of shields. I would collect the related shields between headline and text, which are referenced in the text.
      image
    • Maybe this blog post (or made available as a local copy, license?) should be linked in the fork/branching section: http://nvie.com/posts/a-successful-git-branching-model/
    • In the test: See Directory structure uses the title of the reference. It should be either all in upper case like titles are written in US English or in lower case to fit into the text.
    • a list of actions can be written as:
      1. foo 
      1. foo
      
  • License
    • The number of contributors is wrong - it's a bug in the shield itself.
    • Missing Authors:
      • @Jonsba - signal selection
      • @cclassic - vendor pre-compile script for Lattice (linux)

@1138-4EB 1138-4EB force-pushed the 1138-4EB:new-documentation-structure branch 11 times, most recently from 6bfe403 to fc43e76 Feb 22, 2017

@1138-4EB

This comment has been minimized.

Contributor

1138-4EB commented Feb 22, 2017

  • > Why is the documentation content centered?

That is the default behaviour of the RTD theme for screens more than 768px wide but less than max-width, where max-width is somewhere between 768 and 1400. Above 1400px the main container is aligned to the left. However, with Firefox (with Chrome too, I think), you can change it online. Right click at any point and select Inspect element. Then go to theme_overrides.css and change line 17:

  • Centered: .wy-nav-content{margin: auto; max-width: 1020px}
  • Aligned to the left: .wy-nav-content{margin: 0; max-width: 1020px}

I think it looks worse with large screens when it is not centered, than it does with small ones when it is. However, it's just a matter of taste. On mobile devices (small screens) it is always aligned to the left. The default sidebar took most of the screen, so I modified it so that its width does not change.

  • > Why are selected navigation bar items indented?

Should be fixed now. At least levels 1, 2 and 3.

  • > Do we want to use justified text in stead of ragged right? The PoC documentation contains such a style fix.

Can you point me to the correct file?

  • > Page "About GHDL"

    • > I would't write VHDL and GHDl every time in italic. Italic is usually used to introduce a term or wording. So italic is used the first time a word or wording appears, but not repeated.
    • > directive include is broken (visible in text), thus |trade| doesn't work.
    • > GHW points to a local GHDL parameter, whereas VCD points to wikipedia. (you can create an external link syntax for the English wikipedia if you like.)
      There is no GHW article anywere. So I pointed to the single reference I found.
      I added que external link syntax.
    • Who uses GHDL:
      • PoC
      • VUnit
      • IEEE P1076 WG
  • Page "Contributing"

    • I wouldn't use shields in the text. That's not the purpose of shields. I would collect the related shields between headline and text, which are referenced in the text.
    • Maybe this blog post (or made available as a local copy, license?) should be linked in the fork/branching section: http://nvie.com/posts/a-successful-git-branching-model/
    • In the test: See Directory structure uses the title of the reference. It should be either all in upper case like titles are written in US English or in lower case to fit into the text.
    • a list of actions can be written as
  • License

    • The number of contributors is wrong - it's a bug in the shield itself.
      Mine is showing the same number as this GitHub page (21). Maybe ctrl+f5? img.shields.io allows to Set the HTTP cache lifetime in secs with ?maxAge=3600. Should I add it to every badge?
    • Missing Authors:
      • @Jonsba - signal selection
      • @cclassic - vendor pre-compile script for Lattice (linux)

@1138-4EB 1138-4EB force-pushed the 1138-4EB:new-documentation-structure branch 12 times, most recently from e5bbee9 to c26107c Feb 22, 2017

Add theme_overrrides.css
Move WhatIs* to About. Move About, Contributing and Copying to doc. Rename Copying to License. Append CC-BY-SA-4.0 legalcode to COPYING.md
Chapter Introduction ready for review.
Starting to rewrite Building

@Paebbels Paebbels merged commit 509673e into ghdl:new-documentation-structure Feb 22, 2017

1 of 2 checks passed

continuous-integration/appveyor/pr Waiting for AppVeyor build to complete
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@1138-4EB

This comment has been minimized.

Contributor

1138-4EB commented Feb 22, 2017

@tgingold activated new-documentation-structure version in RTD but it won't build. Leaving this note here just to remember: in RTD, settings, advanced settings, put doc/requirements.txt in the requirements box, and uncheck the box that generates the EPUB version. Indeed, although the build failed, HTML and PDF version where being properly generated.

On top of that, since SVG images are used, those are not shown in PDF. That's because LaTeX is used. Maybe a package could be added to convert them, or we can have them replaced with text for the LaTeX version. However, I think that it's better to check it after we finish rewriting the whole documentation.


The merge that @Paebbels did this morning had a couple of minor issues (the gitter shield link being broken, and the scroll bar being visible in small screens). They are fixed in my new-documentation-structure branch, which is a single commit ahead. You can either pull, or just wait until I finish rewritting the next chapter and I'll PR for all together.

@Paebbels

This comment has been minimized.

Member

Paebbels commented Feb 22, 2017

It's not a productive branch nor a major issue, so I'll wait :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment