Amend Codeblocks, add highlight and format markdown #389

jason-fox · 2019-03-26T10:46:23Z

This PR fixes the white-code-on-a-white-background issue found in the current Wirecloud documentation:

The existing pymdownx.superfences and codehilite extensions conflict with the standard FIWARE CSS settings. I've commented out the extensions and added appropriate code syntax throughout the documentation. I've also formatted the markdown to avoid any other ReadTheDocs rendering issues

aarranz

Hi @jason-fox, thank you very much for your contribution!

I have done only a first review as you are making a very big change, but this is a first batch of things that I think should be changed before merging.

Best regards.

aarranz · 2019-03-26T10:59:25Z

docs/installation_guide.md


-```
+```text


This block contains a shell script (with comments but a shell script)

Fixed fb9c400

aarranz · 2019-03-26T11:06:01Z

docs/installation_guide.md

-documentation](https://channels.readthedocs.io/en/latest/deploying.html).
+-   Install [Django channels](https://channels.readthedocs.io/en/latest/):
+
+```bash


This block has lost indentation (due pymdownx.superfences removal)

Not done, since <zbr> should be sufficient:

aarranz · 2019-03-26T11:46:47Z

mkdocs.yml

@@ -33,16 +33,16 @@ markdown_extensions:
    - pymdownx.betterem
    - pymdownx.tilde:
        subscript: False
-    - pymdownx.superfences
+#    - pymdownx.superfences


This extension is not conflicting at all, it is only conflicting when using it jointly with the codehilite extension, that is the extension conflicting with the highlight.js library used by the FIWARE Style. So, please, maintain the pymdownx.superfences extension and revert all the changes required due to its removal.

Superfences is causing an issue - compare this:

With the proper XML style shown below.

Font is too small to read attributes have a hard black background, the red has insufficient contrast - superfences just makes this ugly (and there is a fix for blocks - see below)

I've removed both of the extensions for improved readability. Fixed - 811dbf4

codehighlight is causing the white background

superfences has font size and highlighting issues.

Neither extension is used elsewhere in the FIWARE documentation

aarranz · 2019-03-26T11:47:38Z

mkdocs.yml

    - pymdownx.magiclink:
        repo_url_shortener: True
        repo_url_shorthand: True
        provider: "github"
        user: "Wirecloud"
        repo: "wirecloud"
    - pymdownx.tasklist
-    - codehilite:
-        guess_lang: False
+#    - codehilite:


If the extension is problematic, we should remove it from mkdocs.yml instead of commenting it.

Fixed 811dbf4 - Extensions removed

aarranz · 2019-03-26T12:04:28Z

docs/installation_guide.md

-        $ git clone https://github.com/Wirecloud/wirecloud.git
-        $ cd wirecloud
-        $ git checkout 1.0.x
+```bash


Fix indentation (pymdownx.superfences)

Not Done - color should be sufficient here:

aarranz · 2019-03-26T12:25:53Z

docs/installation_guide.md

-WireCloud in this case for a production ready environment, in the meantime, you
-can take a look into the [Django channels
-documentation](https://channels.readthedocs.io/en/latest/deploying.html).
+-   Install [Django channels](https://channels.readthedocs.io/en/latest/):


Recover step numbers (lost due pymdownx.superfences removal)

It is possible to get the step numbers back without superfences through judicious use of the <zbr> directive as shown:

As you can see, there is a slight indent, and the code is highly readable.

Fixed fb9c400

aarranz · 2019-03-26T12:53:10Z

docs/installation_guide.md

-    >>> django.VERSION
-    (1, 5, 5, 'final', 0)
+```bash
+$ python


One block using the console language. Splitting here is weird.

Fixed fb9c400

aarranz · 2019-03-26T13:10:06Z

docs/installation_guide.md

-[Solr]: http://lucene.apache.org/solr/
-[ElasticSearch2]: https://www.elastic.co/products/elasticsearch
-[Whoosh]: https://whoosh.readthedocs.io/en/latest/
+[solr]: http://lucene.apache.org/solr/


Although this is not breaking documentation, I'm curious, why to change them to low case if the references on the paragraphs maintains the capitalisation?

Fixed fb9c400 - I've inlined the URLs - it is better markdown practice anyway.

aarranz · 2019-03-26T13:40:40Z

docs/installation_guide.md


 #### Apache 2.2

 You can use this template as starting point:

-```ApacheConf
+```xml


It would be great if the FIWARE style provides some fixes for the horrendous colours used by hightlight.js for the apacheconf language. It's the only reason to allow you to use xml here, hehe.

The FIWARE XML colours are quite harmonious, and work well over soft black:

And perhaps more importantly they are consistent.

Well, I mean the colours applied when using the apacheconf language:

I mainly complain about the red colour, but if you find it harmonious, then switch them back to use apacheconf 😉. apacheconf is the correct language for apache config files (they are not xml files).

With the current colour scheme, I prefer to use the xml language 😄.

Ahhhh - got it. But as you can see (ignoring the red for the moment) it is now using FIWARE CSS Pink, Yellow and Purple. This means improving the brightness of the red would just be another CSS change on within the CSS files held by the FIWARE Foundation.

I can look into that after this PR has been processed. Let's leave it XML for now and potentially change it again later.

aarranz · 2019-03-26T13:41:37Z

docs/installation_guide.md

-    www-data  3818  3811  0 68663 39820   0 13:13 ?        00:00:00 /usr/sbin/apache2 -k start
-    www-data  3819  3811  0 68687 39448   0 13:13 ?        00:00:00 /usr/sbin/apache2 -k start
-    www-data  3822  3811  0 68901 40160   0 13:13 ?        00:00:00 /usr/sbin/apache2 -k start
+```bash


don't split, use the console language.

Unfortunately your default choices here are bash or text - console isn't supported on readthedocs.

Split removed fb9c400

coveralls · 2019-03-26T15:38:45Z

Coverage decreased (-0.005%) to 78.875% when pulling 5014013 on jason-fox:feature/codeblock into c177864 on Wirecloud:develop.

coveralls · 2019-03-26T15:38:47Z

Coverage remained the same at 78.88% when pulling 811dbf4 on jason-fox:feature/codeblock into c177864 on Wirecloud:develop.

Amend Codeblocks, add highlight and format markdown

9a9b7c1

aarranz self-requested a review March 26, 2019 11:39

aarranz requested changes Mar 26, 2019

View reviewed changes

jason-fox added 2 commits March 26, 2019 14:53

First round of fixes

fb9c400

Remove superfences and codehilite

811dbf4

Remove split

5014013

aarranz merged commit 27abd2d into Wirecloud:develop Mar 27, 2019

jason-fox mentioned this pull request Apr 2, 2019

New ReadTheDocs Documentation telefonicaid/perseo-fe#330

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Amend Codeblocks, add highlight and format markdown #389

Amend Codeblocks, add highlight and format markdown #389

jason-fox commented Mar 26, 2019

aarranz left a comment

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019 •

edited

Loading

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019

aarranz Mar 26, 2019 •

edited

Loading

jason-fox Mar 27, 2019

aarranz Mar 27, 2019

aarranz Mar 26, 2019

jason-fox Mar 26, 2019 •

edited

Loading

coveralls commented Mar 26, 2019 •

edited

Loading

coveralls commented Mar 26, 2019


		```
		```text

Amend Codeblocks, add highlight and format markdown #389

Amend Codeblocks, add highlight and format markdown #389

Conversation

jason-fox commented Mar 26, 2019

aarranz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jason-fox Mar 26, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aarranz Mar 26, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jason-fox Mar 26, 2019 • edited Loading

Choose a reason for hiding this comment

coveralls commented Mar 26, 2019 • edited Loading

coveralls commented Mar 26, 2019

jason-fox Mar 26, 2019 •

edited

Loading

aarranz Mar 26, 2019 •

edited

Loading

jason-fox Mar 26, 2019 •

edited

Loading

coveralls commented Mar 26, 2019 •

edited

Loading