README format from md to rst #288

fragmuffin · 2018-07-20T13:16:01Z

addresses issue #287

AppVeyorBot · 2018-07-20T13:25:10Z

✅ Build cadquery 1.0.63 completed (commit 949034518a by @fragmuffin)

coveralls · 2018-07-20T13:25:39Z

Coverage remained the same at 92.28% when pulling cdcea63 on fragmuffin:feature/readme-rst into 15e567f on dcowden:master.

codecov-io · 2018-07-20T13:25:45Z

Codecov Report

Merging #288 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #288   +/-   ##
=======================================
  Coverage   92.79%   92.79%           
=======================================
  Files          10       10           
  Lines        2207     2207           
=======================================
  Hits         2048     2048           
  Misses        159      159

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 6251ec0...1024b65. Read the comment docs.

AppVeyorBot · 2018-07-20T13:32:44Z

❌ Build cadquery 1.0.64 failed (commit 511a192211 by @fragmuffin)

fragmuffin · 2018-07-20T13:37:59Z

oh! I just noticed that PyPI can handle Markdown 🙄
Is that new?; I thought it only handled rst.
Not sure if this is a good change then... perhaps I should have stuck with md.

westurner · 2018-07-20T15:05:51Z

Sphinx can also handle markdown; though roles and directives are not implemented for markdown, so it makes sense for README to be in RST so that it can easily be included in the docs verbatim.

Thanks!

dcowden · 2018-07-21T20:29:16Z

Ok so the consensus is that this is ready to merge?

fragmuffin · 2018-07-22T02:31:20Z

@dcowden

There are also minor changes to:

Dockerfile
setup.py

But if there are any unforeseen issues with those, I'm sure they can be fixed easily in the next release.

fragmuffin · 2018-07-22T11:24:26Z

Oh, also... have a look at the result before you merge it in:
https://github.com/fragmuffin/cadquery/tree/feature/readme-rst

Although it should technically be the same, it seems the :align: center and :width 350 px parameters for img tags aren't being rendered by github... everything else is the same.

I'll just play with that for a bit; see if I can get the formatting working...

AppVeyorBot · 2018-07-22T11:48:56Z

✅ Build cadquery 1.0.65 completed (commit cc8c05e37a by @fragmuffin)

AppVeyorBot · 2018-07-22T12:33:40Z

✅ Build cadquery 1.0.66 completed (commit 8ad0e61b9d by @fragmuffin)

AppVeyorBot · 2018-07-22T12:45:21Z

✅ Build cadquery 1.0.67 completed (commit 30ac67c6b5 by @fragmuffin)

AppVeyorBot · 2018-07-22T12:54:49Z

✅ Build cadquery 1.0.68 completed (commit cde44c8ae0 by @fragmuffin)

fragmuffin · 2018-07-22T13:00:42Z

Hmph 😞. I've played around a bit with the images, but I've come around full circle.
It seems the attributes are being picked up when rendering
eg: see alt="Binder" for pill in I just want to try things out
But :align: and :width: are (mostly) ignored.

*mostly?
Both :width: and :align: attributes are rendered in the logo img tag at the top, but the align attribute is deprecated in HTML5 (see: github/markup#163).
The question remains: how to center align an image when rendered to HTML5?
However, further down in the readme, neither :width: nor :align: are rendered to the KiCad img tag.

I'm so confused 😕

Does anyone have:

experience with rendering images in reStructured text?, or
a better idea for a solution to DOC: pypi long_description is broken #287

dcowden · 2018-07-22T15:44:57Z

@fragmuffin the cadquery spinx docs render images. For example, quickstart:
https://github.com/dcowden/cadquery/blob/master/doc/quickstart.rst

For a more advanced case, the cq examples uses a custom directive (cqplot) that executes cq script and then creates an image and embeds it.

fragmuffin · 2018-07-24T02:28:51Z

@dcowden Sphinx must be using a different renderer, because it seems to be working in other examples as well.
But it looks like the github markup rst img width being ignored is a known issue github/markup#295 but won't be fixed 😢.

I'll try the proposed :scale: fix tonight to see if that's any better.

AppVeyorBot · 2018-07-24T08:51:32Z

✅ Build cadquery 1.0.69 completed (commit f7a3cb1ee0 by @fragmuffin)

fragmuffin · 2018-07-24T08:59:13Z

OK!, I'm so very done with this...
I gave up with image and figure and reverted any scaled images to use the .. raw:: html directive.

So the equivalent of:

.. image:: https://foo.com/bar.png

    :width: 100px
    :align: center

which doesn't render properly, ref: github/markup#295 ... is:

.. raw:: html

    <div align="center">
        <img src="https://foo.com/bar.png" width="100px" />
    </div>

Now... At this point I'm assuming this will render the same in PyPI as it does in github.
All link targets and image sources are absolute (same as before), so there shouldn't be any problems there.

AppVeyorBot · 2018-07-24T09:01:29Z

✅ Build cadquery 1.0.70 completed (commit 425f9c9791 by @fragmuffin)

fragmuffin · 2018-09-17T03:08:51Z

@westurner what do you think? is it time to merge?

westurner · 2018-09-17T03:31:02Z

README.rst

+Thanks go to cadquery contributor hyOzd ( Altu Technology ) for the example!
+
+
+KiCad uses cadquery to build high quality models of electrictronic components. (`https://github.com/KiCad/packages3D <https://github.com/KiCad/packages3D>`_)


'electrictronic'

westurner · 2018-09-17T03:31:50Z

README.rst

+
+CadQuery has several goals:
+
+* Build lD models with scripts that are as close as possible to how you'd describe the object to a human.


IDK what this is: "lD models"

westurner · 2018-09-17T03:32:46Z

README.rst

+
+If you are familiar with jQuery, you will probably recognize several jQuery features that CadQuery uses:
+
+* A fluent api to create clean, easy to read code


westurner · 2018-09-17T03:33:14Z

README.rst

+
+CadQuery scripts have several key advantages over OpenSCAD:
+
+#. **The scripts use a standard programming language**, python, and thus can benefit from the associated infrastructure.


python -> Python

westurner · 2018-09-17T03:35:03Z

Conda install instructions would be great, too:

conda install -c conda-forge freecad notebook cadquery?

AppVeyorBot · 2018-09-17T11:46:28Z

✅ Build cadquery 1.0.81 completed (commit 4c13418b45 by @fragmuffin)

AppVeyorBot · 2018-09-17T11:54:56Z

✅ Build cadquery 1.0.82 completed (commit 6fadbccbd1 by @fragmuffin)

fragmuffin · 2018-09-17T11:59:51Z

@westurner good suggestions ;)
I've added the conda instruction in cdcea63 (which will publish the installation.html page) ... I've simplified it to:

conda install -c conda-forge cadquery

Although I didn't test it...
@dcowden @jmwright @adam-urbanczyk : Is that the recommended way to install cadquery using anaconda?; or do you have to explicitly reference FreeCAD as well when installing?

AppVeyorBot · 2018-09-17T12:02:36Z

✅ Build cadquery 1.0.83 completed (commit c690feaedc by @fragmuffin)

adam-urbanczyk · 2018-09-18T06:37:30Z

@fragmuffin it should be

conda install -c conda-forge cadquery

This works, but does not install all dependencies (e.g. FreeCad). So I have to conclude that the package is currently broken. Does anyone remember how was the conda-forge recipe prepared?

adam-urbanczyk · 2018-09-18T06:48:27Z

Adding for reference: conda-forge/cadquery-feedstock#2

Short memory: #169

fragmuffin · 2018-09-18T08:31:21Z

@adam-urbanczyk excellent, thanks.
So I think this is ready to merge... @dcowden @jmwright what do you think?

jmwright · 2018-09-18T11:41:33Z

@fragmuffin @adam-urbanczyk

I have not used rst before. I'm assuming I'll have to learn its new markup format?

If the broken conda line isn't a showstopper, I think this is fine to merge.

fragmuffin · 2018-09-19T02:56:55Z

@jmwright

I'm assuming I'll have to learn its new markup format?

Yes, it's a little different to markdown, but it has the same sentiment; the non-formatted text still gives a sense of hierarchy and format so it's easy to read.
I highly recommend learning it, especially when coding sphinx with Python, which cadquery does.

I often get markups mixed up, so I use an online editor for basic verification of rst format.
However, as this PR has demonstrated, there are nuances with different renderers that can cause issues.
But I think we've accurately assessed that the benefits of rst outweigh the negatives, in this case.

I've added a check to TravisCI that should fail a bad edit to the README.rst

If the broken conda line isn't a showstopper, I think this is fine to merge.

It is an issue, but out of scope for this PR

jmwright · 2018-09-19T12:04:56Z

@dcowden Are you ok with this being merged?

dcowden · 2018-09-19T16:43:12Z

@jmwright @fragmuffin definitely!

jmwright · 2018-09-19T17:54:23Z

@fragmuffin @westurner @adam-urbanczyk Thanks for the work on this.

westurner · 2018-09-19T17:56:56Z

Thanks!

…

On Wednesday, September 19, 2018, Jeremy Wright ***@***.***> wrote: @fragmuffin <https://github.com/fragmuffin> @westurner <https://github.com/westurner> @adam-urbanczyk <https://github.com/adam-urbanczyk> Thanks for the work on this. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#288 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADGyyJh-NopDUH4BrV5bv3XrTdPjNj0ks5ucoTUgaJpZM4VYBGw> .

westurner · 2018-09-19T17:59:19Z

This could be an https link: http://dcowden.github.io/cadquery

…

On Wednesday, September 19, 2018, Wes Turner ***@***.***> wrote: Thanks! On Wednesday, September 19, 2018, Jeremy Wright ***@***.***> wrote: > @fragmuffin <https://github.com/fragmuffin> @westurner > <https://github.com/westurner> @adam-urbanczyk > <https://github.com/adam-urbanczyk> Thanks for the work on this. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#288 (comment)>, > or mute the thread > <https://github.com/notifications/unsubscribe-auth/AADGyyJh-NopDUH4BrV5bv3XrTdPjNj0ks5ucoTUgaJpZM4VYBGw> > . >

westurner · 2018-09-19T18:04:00Z

The images in https://github.com/dcowden/cadquery/blob/master/README.rst#projects-using-cadquery are 404ing? http://dcowden.github.io/cadquery/_static/hyOzd-finished_thumb.jpg ... A link to OpenCascade might be good: https://en.wikipedia.org/wiki/Open_Cascade_Technology

…

On Wednesday, September 19, 2018, Wes Turner ***@***.***> wrote: This could be an https link: http://dcowden.github.io/cadquery On Wednesday, September 19, 2018, Wes Turner ***@***.***> wrote: > Thanks! > > On Wednesday, September 19, 2018, Jeremy Wright ***@***.***> > wrote: > >> @fragmuffin <https://github.com/fragmuffin> @westurner >> <https://github.com/westurner> @adam-urbanczyk >> <https://github.com/adam-urbanczyk> Thanks for the work on this. >> >> — >> You are receiving this because you were mentioned. >> Reply to this email directly, view it on GitHub >> <#288 (comment)>, >> or mute the thread >> <https://github.com/notifications/unsubscribe-auth/AADGyyJh-NopDUH4BrV5bv3XrTdPjNj0ks5ucoTUgaJpZM4VYBGw> >> . >> >

jmwright · 2018-09-19T18:06:56Z

@westurner The images show up for me.

westurner · 2018-09-19T18:15:57Z

Must've taken a minute for GH pages to check out master and flush the cache. This isn't displaying: https://github.com/RustyVermeer/cqnb/raw/master/showcase.gif The readme links to https://github.com/RustyVermeer/cqnb/blob/master/showcase.gif IDK if it's still necessary to append ``?raw=true``? https://github.com/RustyVermeer/cqnb/blob/master/showcase.gif?raw=true

…

On Wednesday, September 19, 2018, Jeremy Wright ***@***.***> wrote: @westurner <https://github.com/westurner> The images show up for me. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#288 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADGy1entHir1WrAEDLFmjyw2fD-uRKVks5ucofIgaJpZM4VYBGw> .

README.rst

doc/installation.rst

fragmuffin · 2018-09-22T11:10:23Z

The showcase.gif link is still an issue.
I've made #294 to fix it.

fragmuffin added 4 commits July 20, 2018 22:47

converted md to rst

9f1ef61

format fixes

2f21b06

image width units to px

6b1daed

README.md -> README.rst from search results

159c9af

fragmuffin added 2 commits July 22, 2018 21:39

auto-numbered list fix

4781065

img formatting test

20072ab

3 spaces test

f019662

fragmuffin added 2 commits July 22, 2018 22:36

reverted indentation to standard 4-spaces

a4da15f

missed H2s

7de08ba

fragmuffin added 2 commits July 24, 2018 18:42

resized imaged with raw html

f15cb2c

minor format fixes

1024b65

westurner mentioned this pull request Sep 16, 2018

Allow width, height, alt, and align attributes on img tags. pypa/readme_renderer#91

Merged

westurner reviewed Sep 17, 2018

View reviewed changes

fragmuffin added 2 commits September 17, 2018 21:37

python -> Python

79c6606

suggested changes by review

01e9193

conda installation instruction

cdcea63

jmwright merged commit 938261b into dcowden:master Sep 19, 2018

westurner reviewed Sep 19, 2018

View reviewed changes

README.rst Show resolved Hide resolved

doc/installation.rst Show resolved Hide resolved

		Thanks go to cadquery contributor hyOzd ( Altu Technology ) for the example!


		KiCad uses cadquery to build high quality models of electrictronic components. (`https://github.com/KiCad/packages3D <https://github.com/KiCad/packages3D>`_)


		CadQuery has several goals:

		* Build lD models with scripts that are as close as possible to how you'd describe the object to a human.


		If you are familiar with jQuery, you will probably recognize several jQuery features that CadQuery uses:

		* A fluent api to create clean, easy to read code


		CadQuery scripts have several key advantages over OpenSCAD:

		#. The scripts use a standard programming language, python, and thus can benefit from the associated infrastructure.

README format from md to rst #288

README format from md to rst #288

Conversation

fragmuffin commented Jul 20, 2018

AppVeyorBot commented Jul 20, 2018

coveralls commented Jul 20, 2018 • edited Loading

codecov-io commented Jul 20, 2018 • edited Loading

Codecov Report

AppVeyorBot commented Jul 20, 2018

fragmuffin commented Jul 20, 2018

westurner commented Jul 20, 2018

dcowden commented Jul 21, 2018

fragmuffin commented Jul 22, 2018 • edited Loading

fragmuffin commented Jul 22, 2018 • edited Loading

AppVeyorBot commented Jul 22, 2018

AppVeyorBot commented Jul 22, 2018

AppVeyorBot commented Jul 22, 2018

AppVeyorBot commented Jul 22, 2018

fragmuffin commented Jul 22, 2018

dcowden commented Jul 22, 2018

fragmuffin commented Jul 24, 2018

AppVeyorBot commented Jul 24, 2018

fragmuffin commented Jul 24, 2018 • edited Loading

AppVeyorBot commented Jul 24, 2018

fragmuffin commented Sep 17, 2018

westurner Sep 17, 2018

Choose a reason for hiding this comment

westurner Sep 17, 2018

Choose a reason for hiding this comment

westurner Sep 17, 2018

Choose a reason for hiding this comment

westurner Sep 17, 2018

Choose a reason for hiding this comment

westurner commented Sep 17, 2018

AppVeyorBot commented Sep 17, 2018

AppVeyorBot commented Sep 17, 2018

fragmuffin commented Sep 17, 2018

AppVeyorBot commented Sep 17, 2018

adam-urbanczyk commented Sep 18, 2018

adam-urbanczyk commented Sep 18, 2018 • edited Loading

fragmuffin commented Sep 18, 2018

jmwright commented Sep 18, 2018

fragmuffin commented Sep 19, 2018 • edited Loading

jmwright commented Sep 19, 2018

dcowden commented Sep 19, 2018

jmwright commented Sep 19, 2018

westurner commented Sep 19, 2018 via email

westurner commented Sep 19, 2018 via email

westurner commented Sep 19, 2018 via email

jmwright commented Sep 19, 2018

westurner commented Sep 19, 2018 via email

fragmuffin commented Sep 22, 2018

coveralls commented Jul 20, 2018 •

edited

Loading

codecov-io commented Jul 20, 2018 •

edited

Loading

fragmuffin commented Jul 22, 2018 •

edited

Loading

fragmuffin commented Jul 22, 2018 •

edited

Loading

fragmuffin commented Jul 24, 2018 •

edited

Loading

adam-urbanczyk commented Sep 18, 2018 •

edited

Loading

fragmuffin commented Sep 19, 2018 •

edited

Loading