Migrate the Documentation to Antora #6785
Conversation
|
Is the |
|
The docs are getting imported into the main docs and built there. The client docs don't need to be built standalone anymore with antora. |
|
Looks like it got to be dropped from the root cmake file? |
|
Yes, the client docs should be remain in the client source so that it can go into the rpm/deb. What is wrong with the current way of documenting? |
|
The current sphinx documentation will be replaced by antora docs. |
|
Any reason for that? How about putting energy into the contents, rather than the framework? |
|
That's not my decision, even if I welcome this decision because the setup up Antora is much simpler than this whole sphinx stack. Besides that I personally also prefer ascidoc over rst. |
|
I guess we need some PDF shipped with the client packages. And with the latest tooling of @settermjd we should be able to build a PDF "book". |
|
In openSUSE there is no antora yet. That means I would have trouble building the docs, other distros probably similar. Sphinx is a well know and wide spread technology which everybody has. Shipping a PDF: That is the second best option. I am still dreaming of an openSUSE branded ownCloud client, and that would include the docs. Hardly possible with PDF. I am still trying to understand why you wanna do the change, what is the real benefit of antora? |
|
@michaelstingl @tboerger @settermjd I don't want to judge over the choice of Antora. If it's good it will find it's way into distributions. I'm more worried that the "command line API" to generate them has changed and packagers now need to learn how to use Antora (while they didnt need to know sphinx, just cmake) P.S. asciidoc is pretty readable without generating html or pdf from it |
settermjd
force-pushed
the
master-antora
branch
3 times, most recently
from
fa85734
to
6e62cf7
Compare
|
@dschmidt, thanks for your most recent feedback. It could be possible (likely is) to have the client docs both included in the rest of the documentation, as well as be able to be built standalone. I have to check the Antora docs again. If so, then I'll get a CMake target back in to build them, using the target name. In the main docs repo, I've assembed a basic set of information around AsciiDoc and Antora, along with some of the motivations for making the change (I think). |
|
@settermjd Yep, as I said just a link to that repo in the client's README would be very handy already. |
|
OK, I'll get it done, @dschmidt. |
It's come up discussion around the migration to Antora, that the client docs should be able to be built standalone, and not just as a part of the larger documentation set. By adding an Antora Playbook file (site.yml), the client docs can be built both standalone and as part of the larger ownCloud documentation site. See #6785 (comment)
settermjd
force-pushed
the
master-antora
branch
from
ceb4d84
to
54f640e
Compare
It's come up discussion around the migration to Antora, that the client docs should be able to be built standalone, and not just as a part of the larger documentation set. By adding an Antora Playbook file (site.yml), the client docs can be built both standalone and as part of the larger ownCloud documentation site. See #6785 (comment)
|
I'd argue it's not so relevant what was used before only the current state. We will rewrite it anyway when the CMake target lands .. so for now this is ok to me 👍 |
| @@ -61,6 +61,15 @@ Past maintainers: | |||
| * Daniel Molkentin <daniel@molkentin.de> | |||
| * Andreas Schneider <asn@cryptomilk.org> | |||
|
|
|||
| ## Building the Documentation | |||
|
|
|||
| The documentation has been migrated from Sphinx-Doc to [Antora](https://docs.antora.org/), which is based on [the AsciiDoc format](https://github.com/owncloud/docs/blob/master/docs/getting-started.md). | |||
There was a problem hiding this comment.
I would reference via link else you have to maintain two sides.
Like:
Please see the README.md in https://github.com/owncloud/docs for more information
|
I highly propose to move from Bonus: |
While not strictly necessary, the rename makes it that much clearer for contributors to know what the file is for and whether it's the correct one to edit. It also better organised the "advanced usage" files, so that the file structure is that much more meaningful as well. So, a little bit of work now, to save time later.
As the documentation's using Antora instead of Sphinx-Doc, it's essential to work to take users along on the journey with us. So by documenting the change in the readme, and by providing links to further reading, I hope that they'll be amenable to the change.
After re-reading the relevant section of the Antora documentation, I believe that my previous understanding was incorrect as to how navigation files are built. Consequently I used too much indentation and included an unnecessary header, that was duplicating the name draw from the antora.yml (the component descriptor file).
It's come up discussion around the migration to Antora, that the client docs should be able to be built standalone, and not just as a part of the larger documentation set. By adding an Antora Playbook file (site.yml), the client docs can be built both standalone and as part of the larger ownCloud documentation site. See #6785 (comment)
This commit adds two Antora Playbook files, so that the docs can be built, stand-alone, from the remote repository and from the local working copy. It also documents how to build the docs locally.
I'm not sure why I added the attribute previously, in 0afd511, but it's not necessary, and has caused some confusion. Given that, this commit's removing it.
You can even pass -Dnpm=yarn to use yarn instead of npm.
dschmidt
force-pushed
the
master-antora
branch
from
4e5161f
to
6650c71
Compare
Doc for explaining how to remove remnants of the client on windows.
Create Removing.adoc
|
The build failure seems unrelated to this branch (would be really surprising if documentation changes triggered a failure in code tests). So I'd say: |
|
🎉 🎉 🎉 |
No description provided.