search

Zren / zren.github.io

https://zren.github.io/
12 stars 2 forks source link

Move the kde documentation upstream #4

Open CarlSchwan opened 4 years ago

CarlSchwan commented 4 years ago

Hi Zren, thanks for you work on the widgets documentation and on your widgets :)

I'm currently converting techbase.kde.org to sphinx (invent.kde.org/carlschwan/techbase-kde-org). For the moment this is just a PoC and I only converted a few tutorials. One of the advantage of the new system of using sphinx for the documentation is that we can have autogenerated links to the api documentation, the example code can be tested and downloaded and rst is also a better format to write documentation than the mediawiki syntax.

I would like to know if you are interested in moving your KDE documentation to the new system after I finish porting the existing content of techbase to it.

Also it would be nice if you could add a license to the current documentation (preferably CC-BY-SA-4.0 or something compatible). Cheers, Carl

Zren commented 4 years ago

My widget docs theme is based on Mashape's old API docs. Seems they were bought out though, so I can't give you any good links, only this old screenshot.

I liked their 2 column view as you can see explanation + code side by side.

I also wanted to be able to easily link to a section using the fixed sidebar unlike the current wiki, which your readthedocs theme does have. :+1:

As for RST. I could probably get used to ``inline code``, but needing to indent code blocks would be annoying (reddit/github is the same thing). Then again I'd probably be editing with Sublime instead of the web browser so it'd be easy to indent.

Links are... weird with the trailing _, I can see myself forgetting that. It also looks a lot like inline code compared to markdown (though the URL will make it obvious it's a link).

https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#links-to-external-web-pages

`QApplication <https://doc.qt.io/qt-5/qapplication.html>`_

Can you use inline code formatting inside a link? In markdown it's like:

[`QApplication`](https://doc.qt.io/qt-5/qapplication.html)
[`MouseArea`](https://doc.qt.io/qt-5/qml-qtquick-mousearea.html)
[`DefaultCompactRepresentation.qml`](https://github.com/KDE/plasma-desktop/blob/master/desktoppackage/contents/applet/DefaultCompactRepresentation.qml)
[`translate/merge.sh`](https://github.com/Zren/plasma-applet-lib/blob/master/package/translate/merge)
CarlSchwan commented 4 years ago

My widget docs theme is based on Mashape's old API docs. Seems they were bought out though, so I can't give you any good links, only this old screenshot.

I liked their 2 column view as you can see explanation + code side by side.

Yeah, this looks like a good idea. The theme is still in progress and I will take a look at how feasible it is to this sort of things with a custom sphinx theme. I also want to support multiples languages similary like it was done in https://gtk.org/.

I also wanted to be able to easily link to a section using the fixed sidebar unlike the current wiki, which your readthedocs theme does have. +1

As for RST. I could probably get used to inline code, but needing to indent code blocks would be annoying (reddit/github is the same thing). Then again I'd probably be editing with Sublime instead of the web browser so it'd be easy to indent.

Currently for big code block, I prefer including a file from the file system instead. This has the advantage of putting all the file needed for a project in the same directory and create a downloadable and testable examples at the same time.

Links are... weird with the trailing _, I can see myself forgetting that. It also looks a lot like inline code compared to markdown (though the URL will make it obvious it's a link).

https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#links-to-external-web-pages

`QApplication <https://doc.qt.io/qt-5/qapplication.html>`_

Completely agree that link are weird in rst, hopefully I will use the doxylink extension for the Qt api so that we can write: :qtcoreapi:QApplication to add a link to the QApplication doc and :qtcoreapi:QApplication:myMethod to link to a specific method inside the QApplication class.

Can you use inline code formatting inside a link? In markdown it's like:

[`QApplication`](https://doc.qt.io/qt-5/qapplication.html)
[`MouseArea`](https://doc.qt.io/qt-5/qml-qtquick-mousearea.html)
[`DefaultCompactRepresentation.qml`](https://github.com/KDE/plasma-desktop/blob/master/desktoppackage/contents/applet/DefaultCompactRepresentation.qml)
[`translate/merge.sh`](https://github.com/Zren/plasma-applet-lib/blob/master/package/translate/merge)

For this I'm not sure but I will look into it :/