Repo directory structure

[jspaaks]

Couple of observations on the directory structure of ad7ca360c3a519b2f5f3722aed438ef877b49d51.

1. Apparently, it's customary to have a lit for literary programming, not a src like we have now.
2. I would like to have a [src|lit]/cpp with the C++ code snippets in it
3. I'd like to move the dependencies deps/lohmann to cpp as well.
4. Probably the above means that /bin also needs to be moved to lower in the tree
5. I'd like to put cypress under tests, so a reader knows what it is conceptually even if they don't know the name cypress
6. Not sure what to do with apache2 and cgi-bin (also we have 2 cgi-bins)

[sverhoeven]

1. Can you give some links, I only see lit/ used in https://entangled.github.io/tutorial.html, but all the examples at https://entangled.github.io/examples/ use src/ or no subdir.
2. algorithm, cli and cgi are OK for me, what about the bindings? Alternativly have cpp/src with the Cpp chapter as cpp/README.md so each language has a main dir
3. OK for me, we are only using it in the CGI chapter so we could even move it to a cgi specific folder
4. agree
5. As we are using the defaults we would need a config file (.cypress.json) to change all the cypress folders. So then readers will have questions about that.
6. Correct /cgi-bin is no longer used and should be removed. We could rename /apache to /cpp/cgi to correspond with the chapter name. And have cgi-newtonraphson.cpp in /cpp/cgi/src .

[jspaaks]

@1. I based this off of entangled's claim; the only supporting example I could find was https://github.com/zyedidia/Literate. I find src more recognizable, so let's keep that.

[jspaaks]

@ 2, 3, 4, 6 I was able to do the main parts of the guide with the following layout, which I think is more readable:

.
├── cgi
│   ├── apache2
│   ├── cgi-newtonraphson.cpp
│   └── deps
├── cli
│   ├── algebra.hpp
│   ├── cli-newtonraphson.cpp
│   ├── newtonraphson.exe
│   └── newtonraphson.hpp
├── flask
│   ├── newtonraphsonpy.cpython-36m-x86_64-linux-gnu.so -> ../swagger/newtonraphsonpy.cpython-36m-x86_64-linux-gnu.so
│   └── webapp.py
├── react
│   ├── app.js
│   ├── example-app.html
│   ├── newtonraphsonwasm.js -> ../webassembly/newtonraphsonwasm.js
│   ├── newtonraphsonwasm.wasm -> ../webassembly/newtonraphsonwasm.wasm
│   └── worker.js
├── openapi
│   ├── api.py
│   ├── newtonraphsonpy.cpython-36m-x86_64-linux-gnu.so
│   ├── openapi.yaml
│   ├── py-newtonraphson.cpp
│   └── webservice.py
└── webassembly
    ├── example.html
    ├── newtonraphsonwasm.js
    ├── newtonraphsonwasm.wasm
    └── wasm-newtonraphson.cpp

There are a couple of places where we will have duplication, we can either make copies or have softlinks like I did in the tree above.

[sverhoeven]

I like it, some notes

• its not very nested, which I like
• please rename swagger to openapi as that is the current name of it.
• symlinking or copying compiled files seems fragile to me, some possible alternatives
  • for react we could use relative path (../webassenbly/newtonraphsonwasm.wasm)
  • for flask we set PYTHONPATH=openapi python flask/webapp.py

[jspaaks]

• @ 1 same here and it maps more naturally onto the structure of the readme (at least in my brain)
• @ 2 mv swagger openapi done
• @ 3 copying file is also OK, if you think that readers will only choose one method anyway. But it is more of a burden on us devs, to keep things aligned. The downside of both symlinking and the (otherwise valid) approaches you mention is that readers need to step out of their chosen method and read up on another method before they can proceed. I'm wondering if the testing we do, together with using entangled, may be enough to mitigate any potential fragility.

[sverhoeven]

• @3 OK, let's first implement the copy or symlink method and then see if it is fragile

[jspaaks]

Working on this as part of #66 and PR #71.

[jspaaks]

BTW do we want one Makefile or per-method Makefiles?

[sverhoeven]

Many projects use a Makefile in each dir, don't think it will help us much. I like to keep a single Makefile.

[jspaaks]

OK

[sverhoeven]

Lets make separate Makefiles and Markdown will do later.

[sverhoeven]

@jspaaks this issue can be closed now, right?