Well organized documentation for QuISP

[wolfitis]

There are many markdown files in /doc directory that are not easy to follow for people new to QuISP

A well formatted and organized documentation will be a good reference for anyone new to this package. Addition of some basic easy to follow tutorials can be a good starting point for beginners.

To arrange the available docs in some order and link them all together.

Many open source projects have amazing documentations that can be taken as example.

Labels suggestions: [documentation, enhancement]

[zigen]

how about this structure? I think one of the problems is the documentation is far from the actual corresponding source code. The documents that describe the implementation should be put near the source code. For me, it's better than putting whole documents in ./doc directory.

.
├── Authors.md
├── bin
├── dict.txt
├── doc
├── Dockerfile
├── Doxyfile
├── Makefile
├── quisp
│   ├── channels
│   │   └── QuantumChannel.cc
│   ├── classical_messages_m.cc
│   ├── classical_messages_m.h
│   ├── classical_messages.msg
│   ├── Makefile
│   ├── makemakefiles
│   ├── modules
│   │   ├── Application
│   │   │   ├── Application.cc
│   │   │   ├── Application.h
│   │   │   └── README.md
│   │   ├── QRSA
│   │   │   ├── ConnectionManager
│   │   │   │   ├── ConnectionManager.cc
│   │   │   │   ├── ConnectionManager.h
│   │   │   │   └── README.md
│   │   │   ├── HardwareMonitor
│   │   │   │   ├── HardwareMonitor.cc
│   │   │   │   ├── HardwareMonitor.h
│   │   │   │   └── README.md
│   │   │   ├── RealTimeController
│   │   │   │   ├── RealTimeController.cc
│   │   │   │   ├── RealTimeController.h
│   │   │   │   └── README.md
│   │   │   ├── QRSA.ned
│   │   │   └── README.md
│   │   ├── HoM
│   │   │   ├── BellStateAnalyzer
│   │   │   │   ├── BellStateAnalyzer.cc
│   │   │   │   ├── BellStateAnalyzer.h
│   │   │   │   └── README.md
│   │   │   ├── HoMController
│   │   │   │   ├── HoMController.cc
│   │   │   │   ├── HoMController.h
│   │   │   │   └── README.md
│   │   │   ├── HoM.ned
│   │   │   └── README.md

[icepolarizer]

How about using readthedocs.org ? If somebody can assign this to me, I'll do the job.

[rdviii]

I'm not familiar with readthedocs.org. Having something that indexes and creates a table of contents and turns the various markdown files into a single PDF would be useful.

[rdviii]

@zigen your proposal above looks like it's primarily about revising the subdirectory structure for the source, not the documentation?

[rdviii]

Documentation, of course, has multiple purposes. A bunch of what's there so far is either old design docs, some dating back several years, or a narrative/tutorial for beginners, to get them started. Sounds like what @zigen wants is documentation to accompany the code, for coding decisions. That's valuable, and necessary for sound engineering, but we need user's documentation, as well.

[zigen]

yeah, my proposal for developers, not for users. my proposal should be addressed in other issue.

readthedocs seems good. for example, qulacs uses readthedocs and we can download epub.

readthedocs provides downloadable documentation feature. this seems what we need.

[icepolarizer]

Agreed! Also, the integration to GitHub seems to be smooth.

[wolfitis]

What I suggested was the general documentation, it should be easy enough so general users can follow. For developers it shouldn't be an issue to follow the same documentation for contributions. We might not need multiple docs for users and developers.

[rdviii]

It's Wednesday Japan time now...in 5.5 days, we will be doing a tutorial on QuISP for IEEE Quantum Week. Can a useful reorg of docs be completed in that time? If not, we should either branch or plan to start work on it after next week's tutorial.

[icepolarizer]

If you're talking about the conversion of quisp/doc into readthedocs, I think it's possible. Doxygen <-> Readthedocs? If then I can't make it in time.

[rdviii]

Thanks to @icepolarizer we now have a table of contents, which is a good start! See PR #177, merged into master.

[wolfitis]

The links are returning 404 error

[icepolarizer]

Just fixed. Thank you.