docs: Restructure documentation #358
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #358 +/- ##
=======================================
Coverage 97.35% 97.35%
=======================================
Files 72 72
Lines 3818 3821 +3
=======================================
+ Hits 3717 3720 +3
Misses 101 101 ☔ View full report in Codecov by Sentry. |
| @@ -13,6 +13,14 @@ | |||
| # See the License for the specific language governing permissions and | |||
| # limitations under the License. | |||
|
|
|||
| """ | |||
| CVQNN Module | |||
| ============ | |||
There was a problem hiding this comment.
Minor: how come = is used for underlining the title here, but - is used in the subsequent files?
e.g.,
Channels
--------
docs/tutorials/index.rst
Outdated
| :link: separating-programs | ||
| :link-type: doc | ||
|
|
||
| Separate and compose Piquasso programs. |
There was a problem hiding this comment.
The title of this card matches the description: either the title could be shorter or the description could be more elaborate.
|
|
||
| One could easily install Piquasso with the following command: | ||
| .. grid-item-card:: Installation |
There was a problem hiding this comment.
I think these cards are great! Is there a way to set a smaller font size for the description and/or larger one for the titles? Right now the titles and the description have the same font size and that can be visually a bit confusing imho.
E.g., if the text: "Instructions on the installation of the Piquasso package" is 2-4 sizes smaller than the title "Installation", then it's easier to distinguish them and the reader can make a quick choice more easily, if they want to read the description or not.
docs/index.rst
Outdated
| Piquasso is an open source Python package, which allows you to simulate a photonic | ||
| quantum computer. One could use Gaussian or Fock state corresponding to different | ||
| representations to run simulations. | ||
| quantum computer. |
There was a problem hiding this comment.
Minor: this one is a very important sentence, it's like the "mission statement" of the project or at least the one-sentence summary of it. Some (not too over the top) extra formatting could be nice visually.
.readthedocs.yaml
Outdated
| jobs: | ||
| post_install: | ||
| - pip install cmake pybind11[global] | ||
| - cmake -B build -DCMAKE_INSTALL_PREFIX=$(pwd) | ||
| - cmake --build build | ||
| - cmake --install build |
There was a problem hiding this comment.
imho it can be worth leaving a comment here on what the purpose of this step is, e.g., "These steps are required for building the documentation on ReadtheDocs".
The documentation got restructured, and cards have been added with `sphinx-design`. Also, several fixes got issued: - The code blocks didn't render well in the ipython notebooks, and to fix this, the `IPython.sphinxext.ipython_console_highlighting` is added to the extension list in `conf.py`. - Building on ReadtheDocs got fixed by adding the CMake build in a `post_install` job. - The original documentation URLs got modified to the new one. - Some tutorials got updated.
The documentation got restructured, and cards have been added with
sphinx-design.Also, several fixes got issued:
IPython.sphinxext.ipython_console_highlightingis added to the extension list inconf.py.post_installjob.