Sphinx branch #127

dcowden · 2015-11-29T02:59:34Z

This branch, when merged, will put shiney new documentation on

https://dcowden.github.ip/cadquery

(unfortunately, you cannot test pushing the docs because they are only pushed when you do a master branch build )

Before pulling, please build this branch locally, and use ./build-docs.sh to create the documents yourself and see what you think!

I think this is a big step forward. We probably do NOT want to merge this branch though until we work out the details on what the file formats will be. that may get into some changes on cadquery-freecad-module.

jmwright · 2015-11-29T05:42:52Z

This is awesome! I'm very excited to get this documentation up to a state we can be proud of.

I get the following error when I try to build the docs. I can resolve it, but I want to be sure that it won't break the Travis build when we move to master.

no theme named 'sphinx_rtd_theme' found (missing theme.conf?)

On Ubuntu I first had to install python-sphinx as well.

sudo apt-get install python-sphinx

I do have a few thoughts on the content.

You mentioned github.ip in your comment above. I think you meant github.io, and wanted to make sure it wasn't misspelled in a config somewhere and pulled from that.
In some of the screenshots of the CadQuery module you could close the Combo View to give more room for the code pane.
Helpers.show is still referred to in places in the docs. We'll have to remember to come back through and clean those up after we figure out the format (which you've mentioned). We'll need to probably go through a deprecation process with Helpers.show so that the transition is not jarring for users.
In some places you have cadquery.CQ.CQ or cadquery.CQ.Workplane, whereas when you code in CadQuery cadquery.Workplane works. Not sure if you were pointing out the semantic structure of the code, or the way it works in practice.
The logo looks good. I didn't realize that CadQuery even had a logo! We'll need to figure out how to create a smaller version of that for the CadQuery-FreeCAD module's workbench entry. Alternatively, we could just go ahead and rename the module to "Scripting" or something like that and then use a generic script icon from FreeCAD too. I've kind of been leaning that way for awhile anyway.
Do we want the docs to refer to any of the video tutorials?

This is great work. It will allow us to clear the decks of issues #22 and #26 that have been hanging around since I first started experimenting with CadQuery. Thanks for all the time you've put into this!

dcowden · 2015-11-29T14:34:52Z

Yeah you should need to install sphinxdoc. That is in Travis already, and
the branch built the docs ok so I know those issues are local.

I think we probably need to make a separate requirements.txt. the one there
is for cq itself, and it needs to stay empty. But we need another one for
if you need to build the docs and other things you are doing for
development. I'll call it requirements-dev.txt

Yep, github.io.

Good point on the deprecation proccess. Let's separately discuss exactly
what the new and old formats are.. then we can write those docs in the file
format section

Regarding cq.cq.workplane.. that's the only way I could figure out to get
the sphinx auto doc to work. When we load cadquery we do from CQ import *,
which changes the name spaces and confuses sphinx.

Of course it would be better to do it the way users see it.

CQ didn't have a logo till yesterday :)

Yes, let's definitely put the videos in, forgot about those. They should be
in getting started or maybe even on the index page. Can you make those
changes on sphinx_branch?

Let's iterate on sphinx branch will we are happy with it then we can merge
it in
On Nov 29, 2015 12:42 AM, "Jeremy Wright" notifications@github.com wrote:

This is awesome! I'm very excited to get this documentation up to a state
we can be proud of.

I get the following error when I try to build the docs. I can resolve it,
but I want to be sure that it won't break the Travis build when we move to
master.

no theme named 'sphinx_rtd_theme' found (missing theme.conf?)

On Ubuntu I first had to install python-sphinx as well.

sudo apt-get install python-sphinx

I do have a few thoughts on the content.

You mentioned github.ip in your comment above. I think you meant
github.io, and wanted to make sure it wasn't misspelled in a config
somewhere and pulled from that.

In some of the screenshots of the CadQuery module you could close
the Combo View to give more room for the code pane.

Helpers.show is still referred to in places in the docs. We'll have
to remember to come back through and clean those up after we figure out the
format (which you've mentioned). We'll need to probably go through a
deprecation process with Helpers.show so that the transition is not jarring
for users.

In some places you have cadquery.CQ.CQ or cadquery.CQ.Workplane,
whereas when you code in CadQuery cadquery.Workplane works. Not sure if you
were pointing out the semantic structure of the code, or the way it works
in practice.

The logo looks good. I didn't realize that CadQuery even had a
logo! We'll need to figure out how to create a smaller version of that for
the CadQuery-FreeCAD module's workbench entry. Alternatively, we could just
go ahead and rename the module to "Scripting" or something like that and
then use a generic script icon from FreeCAD too. I've kind of been leaning
that way for awhile anyway.

Do we want the docs to refer to any of the video tutorials?

This is great work. It will allow us to clear the decks of issues #22
#22 and #26
#26 that have been hanging
around since I first started experimenting with CadQuery. Thanks for all
the time you've put into this!

—
Reply to this email directly or view it on GitHub
#127 (comment).

jmwright · 2015-12-01T02:35:51Z

@dcowden For the videos, should I just start a new section under "prerequisites"?

jmwright · 2015-12-01T02:36:30Z

In quickstart.rst, I mean.

dcowden · 2015-12-01T11:33:20Z

I think we should have links to those videos right on index.rst where the
quick links are. I'd make a new page called video tutorials, and put it in
the list before the quick start. That will make them more prominent. I
think videos are super helpful so I think we want to make them stand out
On Nov 30, 2015 9:36 PM, "Jeremy Wright" notifications@github.com wrote:

In quickstart.rst, I mean.

—
Reply to this email directly or view it on GitHub
#127 (comment).

dcowden · 2015-12-02T03:58:32Z

Ok, check out the newest version of sphinx-branch if you have a chance.

I struggled for literally hours getting the danged docs to work with
cadquery.CQ: turns out i was struggling with a bug in sphinxdoc, so make
sure you get 1.3.2! 1.3.1 is broken.

Anyway, latest version has these improvements:

docs now use cadquery. so it matches what users will see
added links your videos into the index page, and installation page
added requirements-dev.txt, to document requirements for doing
development

See how this version looks. I have not gone back and updated the page about
file formats-- i will do that once we agree on what the format will be.

On Mon, Nov 30, 2015 at 9:36 PM, Jeremy Wright notifications@github.com
wrote:

In quickstart.rst, I mean.

—
Reply to this email directly or view it on GitHub
#127 (comment).

jmwright · 2015-12-02T04:48:03Z

I get the following warning when I run build_docs.sh.

/home/jwright/Dropbox/Jeremy_Documents/CadQuery/Projects/cadquery/doc/intro.rst:45: WARNING: image file not readable: _static/pillowblock.png

jmwright · 2015-12-02T04:51:02Z

The build seems to be messing with the static files, and it looks to me like there's a letter case conflict with the name.

y$ git status
On branch sphinx_branch
Your branch is up-to-date with 'origin/sphinx_branch'.
Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    deleted:    doc/_static/pillowblock.png

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    doc/_static/PillowBlock (Case Conflict).PNG

no changes added to commit (use "git add" and/or "git commit -a")

jmwright · 2015-12-02T05:08:06Z

Although, git thinks I've deleted that file even after I've just cloned the repo. Something's broken here, but I'm not sure what yet.

jmwright · 2015-12-02T05:27:21Z

Ugh, it was a problem caused by my local copy of cadquery being in a Dropbox directory. I'll have to remember that.

…ng issues.

jmwright · 2015-12-02T05:45:46Z

Ok, I committed a few minor changes. Feels good to get those documentation issues from my early days using CadQuery closed.

I'm really happy with the compiled docs. I'm looking forward to getting the file format changes made to CFM and PParts so that we can roll these out.

dcowden · 2015-12-02T12:07:26Z

ok good! I dont want to wait to change pparts, and i think actually it
might be ok to roll these docs out ahead of the changes to CFM too.

my plan is to write the execution environment, and then change the
cq_sphinx directive to use it. that way, the scripts in the examples
bundled in the documentation will match the new format. I'd say that's the
minimium work necessary to consider releasing the docs.

In the documentation, i'll mention that the new format is only for CQ 0.4.0
or greater. then when we release this, we can say that CQ features a new
format beginning with 0.4, but that it is still reverse compatible. Then we
can release this, and then shoot for pparts and CFM to be 'CQ 0.4
compatible'.

does that sound ok?

On Wed, Dec 2, 2015 at 12:45 AM, Jeremy Wright notifications@github.com
wrote:

Ok, I committed a few minor changes. Feels good to get those documentation
issues from my early days using CadQuery closed.

I'm really happy with the compiled docs. I'm looking forward to getting
the file format changes made to CFM and PParts so that we can roll these
out.

—
Reply to this email directly or view it on GitHub
#127 (comment).

jmwright · 2015-12-02T12:54:31Z

Yeah, sounds good.

Should we talk about merging, or at least syncing, the examples for CadQuery and CFM now? CFM has been the one where we've been adding examples and making fixes to existing ones. With a standard CEE in v0.4.0, we could maybe merge the examples into the CadQuery library, and then I could just pull them from the embedded libraries git subtree for the Examples menu of CFM. That way all users will be getting the full benefit of all the examples.

dcowden · 2015-12-02T20:52:48Z

yes that's a good idea. i was also thinking the other way too-- i wanted
the full benefit of all of the CFM examples inside of the CQ documentation
as well.

Yeah, sounds good.

Should we talk about merging, or at least syncing, the examples for
CadQuery and CFM now? CFM has been the one where we've been adding examples
and making fixes to existing ones. With a standard CEE in v0.4.0, we could
maybe merge the examples into the CadQuery library, and then I could just
pull them from the embedded libraries git subtree for the Examples menu of
CFM. That way all users will be getting the full benefit of all the
examples.

—
Reply to this email directly or view it on GitHub
#127 (comment).

jmwright · 2015-12-11T16:20:08Z

Ok, I've looked through the PR and have some thoughts. I don't have much time right now, so I haven't corrected anything myself.

cadquery.egg-info/PKG-INFO - The "Recently Added Features" section is outdated and probably should either be updated or removed.
"onthe" should be "on the" here
I noticed that you took the copyright/license notices out of some of the files. What was the reason for that?
In this line, you say build_output among references to build_object.
"If your" should be "If you" here
"languages to not provide" should be "languages do not provide" here
We haven't really seen plugins materialize for CQ yet: https://github.com/dcowden/cadquery/pull/127/files#diff-5baba5813ed020ae677c54a7868d7986R49
Missing spaces after commas per pep 8: https://github.com/dcowden/cadquery/pull/127/files#diff-f1747d293233dbb0c4a0161f196a1917R557
The second instance of cadquery is spelled wrong here
Line just has "See the" here
What about the meta data here? Does that warrant a bullet point?
Redundant "the" here
Not that it needs to be added to these docs, but CFM has made it into that third party PPA for Ubuntu, so that will make it even easier for those users to install. https://github.com/dcowden/cadquery/pull/127/files#diff-a2b6dc207634372b2221f2285a885e7dR47
Missing capitalization on cadQuery here
"top that face" should be "top of that face" here
Should the add and boolean selectors go here too?
Is this using the new test framework?

Looks good. Thanks for working on this!

dcowden · 2015-12-11T16:45:13Z

ok thanks for the review.

3-- copyright files. it was really cluttering up sphinxdoc-- it puts the
module doc into the output, and there is not an option i could find not to
do that. plus, even if there was, then i couldnt put what i actually want
to be in the doc in there. I concluded that we should just put the
copyright in the front matter, and stop the 'copyright in every file'
madness.

17 --- i did NOT change to a new testing framework. I'd like to change
eventually, but there was insufficient value at the moment.

i'll address the rest this weekend. I should be able to get them done
very quickly-- looks like an hour or two of work at the most.

Then we should have shiney new docs on github ( which that reminds me i
should change the readme to point to the new doc location too )

On Fri, Dec 11, 2015 at 11:20 AM, Jeremy Wright notifications@github.com
wrote:

Ok, I've looked through the PR and have some thoughts. I don't have much
time right now, so I haven't corrected anything myself.

cadquery.egg-info/PKG-INFO - The "Recently Added Features" section
is outdated and probably should either be updated or removed.

"onthe" should be "on the" here
https://github.com/dcowden/cadquery/pull/127/files#diff-82483651ecc3d580d91d705f2cadeb3cR84

I noticed that you took the copyright/license notices out of some
of the files. What was the reason for that?

In this line
https://github.com/dcowden/cadquery/pull/127/files#diff-7520aa40a39f785cbe05a0707c03a809R36,
you say build_output among references to build_object.

"If your" should be "If you" here
https://github.com/dcowden/cadquery/pull/127/files#diff-7520aa40a39f785cbe05a0707c03a809R64

"languages to not provide" should be "languages do not provide" here
https://github.com/dcowden/cadquery/pull/127/files#diff-5baba5813ed020ae677c54a7868d7986R41

We haven't really seen plugins materialize for CQ yet:
https://github.com/dcowden/cadquery/pull/127/files#diff-5baba5813ed020ae677c54a7868d7986R49

Missing spaces after commas per pep 8:
https://github.com/dcowden/cadquery/pull/127/files#diff-f1747d293233dbb0c4a0161f196a1917R557

The second instance of cadquery is spelled wrong here
https://github.com/dcowden/cadquery/pull/127/files#diff-019f0fe09fe146617a70e65c15c45961R10

Line just has "See the" here
https://github.com/dcowden/cadquery/pull/127/files#diff-019f0fe09fe146617a70e65c15c45961R17

What about the meta data here
https://github.com/dcowden/cadquery/pull/127/files#diff-019f0fe09fe146617a70e65c15c45961R20?
Does that warrant a bullet point?

Redundant "the" here
https://github.com/dcowden/cadquery/pull/127/files#diff-a2b6dc207634372b2221f2285a885e7dR45

Not that it needs to be added to these docs, but CFM has made it
into that third party PPA for Ubuntu, so that will make it even easier for
those users to install.
https://github.com/dcowden/cadquery/pull/127/files#diff-a2b6dc207634372b2221f2285a885e7dR47

Missing capitalization on cadQuery here
https://github.com/dcowden/cadquery/pull/127/files#diff-a2b6dc207634372b2221f2285a885e7dR54

"top that face" should be "top of that face" here
https://github.com/dcowden/cadquery/pull/127/files#diff-dce4048f760a2254db20f3a78d7fcfa1R164

Should the add and boolean selectors go here
https://github.com/dcowden/cadquery/pull/127/files#diff-a994cee866db1c265774f52f68af386dR53
too?

Is this
https://github.com/dcowden/cadquery/pull/127/files#diff-de8241af1615e0c384f13e9c7f3a6419R2
using the new test framework?

Looks good. Thanks for working on this!

—
Reply to this email directly or view it on GitHub
#127 (comment).

dcowden · 2015-12-12T20:25:02Z

On Fri, Dec 11, 2015 at 11:20 AM, Jeremy Wright notifications@github.com
wrote:

Ok, I've looked through the PR and have some thoughts. I don't have much
time right now, so I haven't corrected anything myself.

cadquery.egg-info/PKG-INFO - The "Recently Added Features" section
is outdated and probably should either be updated or removed.

Removed

"onthe" should be "on the" here
https://github.com/dcowden/cadquery/pull/127/files#diff-82483651ecc3d580d91d705f2cadeb3cR84

Fixed

I noticed that you took the copyright/license notices out of some
of the files. What was the reason for that?

Replied to this earlier. its so that the documentation isn't messed up.
I think the license in the front matter is enough.

In this line
https://github.com/dcowden/cadquery/pull/127/files#diff-7520aa40a39f785cbe05a0707c03a809R36,
you say build_output among references to build_object.

Fixed

"If your" should be "If you" here
https://github.com/dcowden/cadquery/pull/127/files#diff-7520aa40a39f785cbe05a0707c03a809R64

Fixed

"

languages to not provide" should be "languages do not provide" here
https://github.com/dcowden/cadquery/pull/127/files#diff-5baba5813ed020ae677c54a7868d7986R41

Fixed

We haven't really seen plugins materialize for CQ yet:
https://github.com/dcowden/cadquery/pull/127/files#diff-5baba5813ed020ae677c54a7868d7986R49

Here's hoping!

Missing spaces after commas per pep 8:
https://github.com/dcowden/cadquery/pull/127/files#diff-f1747d293233dbb0c4a0161f196a1917R557

Fixed most of them.

The second instance of cadquery is spelled wrong here
https://github.com/dcowden/cadquery/pull/127/files#diff-019f0fe09fe146617a70e65c15c45961R10

Fixed

Line just has "See the" here
https://github.com/dcowden/cadquery/pull/127/files#diff-019f0fe09fe146617a70e65c15c45961R17

Fixed

What about the meta data here
https://github.com/dcowden/cadquery/pull/127/files#diff-019f0fe09fe146617a70e65c15c45961R20?
Does that warrant a bullet point?

Added a bit of info here.

Redundant "the" here
https://github.com/dcowden/cadquery/pull/127/files#diff-a2b6dc207634372b2221f2285a885e7dR45

Fixed

Not that it needs to be added to these docs, but CFM has made it
into that third party PPA for Ubuntu, so that will make it even easier for
those users to install.
https://github.com/dcowden/cadquery/pull/127/files#diff-a2b6dc207634372b2221f2285a885e7dR47

Added as an installation method

Missing capitalization on cadQuery here
https://github.com/dcowden/cadquery/pull/127/files#diff-a2b6dc207634372b2221f2285a885e7dR54

Fixed

"

top that face" should be "top of that face" here
https://github.com/dcowden/cadquery/pull/127/files#diff-dce4048f760a2254db20f3a78d7fcfa1R164

Fixed

Should the add and boolean selectors go here
https://github.com/dcowden/cadquery/pull/127/files#diff-a994cee866db1c265774f52f68af386dR53
too?

yes good catch. added some verbiage about that

Is this
https://github.com/dcowden/cadquery/pull/127/files#diff-de8241af1615e0c384f13e9c7f3a6419R2
using the new test framework?

No. i just added it to the existing framework. I didnt feel like changing
frameworks was worth the effort. I think nosetest is much nicer, especially
since the tests do not have to be classes. but given that all of the
classes now are that way, it was way too much to change.

Looks good. Thanks for working on this!

I also changed the license to Apache Public License 2.0. I also made some
changes for the 0.4.0 release.
See what you think.

Added documentation, cqgi, and beginnings of 0.4.0 release

hyOzd · 2015-12-14T22:15:05Z

Link in the first post was wrong. I've been refreshing it for the last couple minutes with no luck until I noticed it : )

It looks and works great! Thanks @dcowden .

dcowden · 2015-12-14T22:20:05Z

yeah sorry about that guys!

But anyway thanks for the conversation. We can keep iterating, but i'm
happy to finally have some decent documentation up there....

On Mon, Dec 14, 2015 at 5:15 PM, Hasan Yavuz ÖZDERYA <
notifications@github.com> wrote:

Link in the first post was wrong. I've been refreshing it for the last
couple minutes with no luck until I noticed it : )

It looks and works great! Thanks @dcowden https://github.com/dcowden .

—
Reply to this email directly or view it on GitHub
#127 (comment).

jmwright · 2015-12-14T23:37:15Z

I agree with @hyOzd Massive improvement! Thanks @dcowden

dcowden added 4 commits November 28, 2015 21:05

Tried to get documentation Into Shape

a967e1f

added travis_sphinx

8aabc4b

fixed build error

a30d631

dont error on warnings

b99a99d

fixed documentation

0959d4b

dcowden added 2 commits December 1, 2015 22:59

fixed dumb travis issue

b5fa3a7

Merge branch 'master' into sphinx_branch

9b0fa9d

Made a few minor edits so that I could close two of my longest standi…

9de84a8

…ng issues.

dcowden added 4 commits December 7, 2015 16:35

beginnings of cqgi

c12e663

initial working version of cqgi

4e2168c

got first directive workign

190980d

workable version of cqgi version

142a5c8

dcowden added 2 commits December 12, 2015 15:08

fixed various documentation errors. changed license to apache

2154a7b

get ready for 0.4.0 release

3a7ff7e

dcowden added 3 commits December 12, 2015 15:33

fixed setup.py issue

7384d9b

removed extraneous build directory

e7d8a92

added build directory to .gitignore

27759d7

dcowden added a commit that referenced this pull request Dec 14, 2015

Merge pull request #127 from dcowden/sphinx_branch

1a89723

Added documentation, cqgi, and beginnings of 0.4.0 release

dcowden merged commit 1a89723 into master Dec 14, 2015

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sphinx branch #127

Sphinx branch #127

dcowden commented Nov 29, 2015

jmwright commented Nov 29, 2015

dcowden commented Nov 29, 2015

jmwright commented Dec 1, 2015

jmwright commented Dec 1, 2015

dcowden commented Dec 1, 2015

dcowden commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

dcowden commented Dec 2, 2015

jmwright commented Dec 2, 2015

dcowden commented Dec 2, 2015

jmwright commented Dec 11, 2015

dcowden commented Dec 11, 2015

dcowden commented Dec 12, 2015

hyOzd commented Dec 14, 2015

dcowden commented Dec 14, 2015

jmwright commented Dec 14, 2015

Sphinx branch #127

Sphinx branch #127

Conversation

dcowden commented Nov 29, 2015

jmwright commented Nov 29, 2015

dcowden commented Nov 29, 2015

jmwright commented Dec 1, 2015

jmwright commented Dec 1, 2015

dcowden commented Dec 1, 2015

dcowden commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

jmwright commented Dec 2, 2015

dcowden commented Dec 2, 2015

jmwright commented Dec 2, 2015

dcowden commented Dec 2, 2015

jmwright commented Dec 11, 2015

dcowden commented Dec 11, 2015

dcowden commented Dec 12, 2015

hyOzd commented Dec 14, 2015

dcowden commented Dec 14, 2015

jmwright commented Dec 14, 2015