Centralized documentation#1129
Conversation
|
Yes, I will review this, but that will be after the patch releases. |
|
How do you generate the documentation with the Edit: I did the following: cd docs/public
mdbook buildThen, once that is done, I can browse |
Indeed. I forgot to provide them. I wasn't sure were to put such documentation. For now, I've updated the PR description with the commands. |
|
I think the best place to add such instructions is the main README.md file. |
|
I’ve had a look at the current file and document structure, comparing |
I've added the commands in the "Documentation" section. |
hannaeko
left a comment
There was a problem hiding this comment.
Nice work!
Could it be interesting to flatten the internal documentation directory by moving all directories inside internal/internal-documentation to internal directly?
That could indeed make sense. I'll provide an update. |
matsduf
left a comment
There was a problem hiding this comment.
The documents from the other repositories, are they just copied as-is or are they also updated? Then I mean updated besides any updates of link location.
There are some documents that are generated or partially generated as described in utils/README.md. That must also be taken care of.
In general this could be a good structure, but we will have to work on the documents after the change too.
| The [public](docs/public) documentation can be built using | ||
| [`mdbook`](https://rust-lang.github.io/mdBook/) and the following commands: | ||
|
|
||
| ``` | ||
| cd docs/public | ||
| mdbook build | ||
| open book/index.html | ||
| ``` |
There was a problem hiding this comment.
Who would be interested in building the documentation into a set of html file (as I understand the result is)? I guess that interest is very limited, maybe limited to the project itself, and not even now but later on.
The information is also very limited, and could probably need some context. I suggest that this information is moved to a file under docs/public where it can be expanded with more details as needed. Here we could keep a link to that document.
There was a problem hiding this comment.
The information is also very limited, and could probably need some context.
What kind of context are you expecting here?
There was a problem hiding this comment.
I cannot say now because I have not tested it, but the text fits better in a separate document. It is not generally relevant.
ghost
left a comment
There was a problem hiding this comment.
The documents from the other repositories, are they just copied as-is or are they also updated? Then I mean updated besides any updates of link location.
There are few updates. See following commits:
de5984d
55d697f
b2c64a3
There are some documents that are generated or partially generated as described in utils/README.md. That must also be taken care of.
Good point. The links have been updated.
| The [public](docs/public) documentation can be built using | ||
| [`mdbook`](https://rust-lang.github.io/mdBook/) and the following commands: | ||
|
|
||
| ``` | ||
| cd docs/public | ||
| mdbook build | ||
| open book/index.html | ||
| ``` |
There was a problem hiding this comment.
The information is also very limited, and could probably need some context.
What kind of context are you expecting here?
The "specification/tests/README.md" is only about the test case specifications, but the "Specification" section has other documents too. |
They have been added to SUMMARY.md |
* use 2 new subfolders "internal" and "public" * move "specification" to "public" * move everything else to "internal" * move "images" folder to new upper folder "assets"
* For Zonemaster-LDNS installation instructions are part of the README file. * For the other components fetch the docs/Installation.md file.
* Zonemaster-LDNS: remove unecessary sections * Update inter document links
* book.toml contains the settings for describing how to build the book * SUMMARY.md contains a list of all the chapters in the book. mdBook: https://rust-lang.github.io/mdBook
and provide commands to build the public documentation
* move "internal-documentation/*" up to "internal" * update old links pointing to "internal-documentation/"
* move "Getting started", "RPCAPI reference" and "Telemetry" documents into this new section * update links
The "Prerequisites" section has been moved to a separate file.
* reinstate some removed sections from commit de5984d * remove Docker section
|
Conflicts have been fixed. @matsduf please re-review. |
marc-vanderwal
left a comment
There was a problem hiding this comment.
I’ve given this PR a second review in order to be sure to catch everything.
As I said before, this way of browsing our documentation is lovely. It makes it much easier to navigate and read. However, the mdbook exposes many latent issues in that documentation that may not have been obvious before.
This means that I may have left review comments that sound like there are still problems to fix, but because this PR isn’t responsible for introducing them, they should not prevent this PR from being merged.
Some other thoughts and ideas for follow-up pull requests follow:
Firstly, I see that the Markdown parser is slightly different from Github’s, in that it’s stricter about the markup it accepts. One good example is the installation instructions document for Zonemaster::Engine where there’s an extraneous space in the link target, as in the excerpt below:
Before installing Zonemaster::CLI from CPAN, you should [install
Zonemaster::Engine][ Zonemaster::Engine installation], unless you are
to install on Debian using pre-built packages (see below).This renders fine on Github, but fails to turn the text into a link in the mdbook. There are other instances of the same problem elsewhere, but that’s for another PR.
Secondly, chiming in with @matsduf: I think parts of the table of contents could be generated automatically, such as the list of test specifications. Until then, new contributions to test specifications should remember to update the TOC in this part.
Thirdly, one of the documents links to documentation generated by perldoc, hosted on metacpan.org. Maybe we could add this perldoc documentation in this documentation, if it’s at all feasible?
| - [Zonemaster-Backend](installation/zonemaster-backend.md) | ||
| - [Zonemaster-GUI](installation/zonemaster-gui.md) | ||
| - [Docker](installation/docker.md) | ||
| - [Upgrade]() |
There was a problem hiding this comment.
I think “Upgrading” works better.
There was a problem hiding this comment.
I'll provide an update in a follow-up PR.
| @@ -0,0 +1,121 @@ | |||
| - [Installation](installation/README.md) | |||
There was a problem hiding this comment.
Does installation/README.md exist?
In the generated mdbook, when I click on “Installation” in the outline (on the left hand side of the page), all I get is an empty page, which is rather awkward.
There was a problem hiding this comment.
It does not exist in the file structure.
There was a problem hiding this comment.
I'll remove the link in a follow-up PR.
| - [GUI](using/gui/README.md) | ||
| - [API](using/gui/api.md) |
There was a problem hiding this comment.
I was expecting a page explaining how to use the graphical user interface from the viewpoint of someone who opens https://zonemaster.fr for example. Having a description of another API here is rather odd.
| @@ -0,0 +1,5 @@ | |||
| # Using the GUI | |||
|
|
|||
| * The [GUI API][API] | |||
There was a problem hiding this comment.
Eventually, we should describe how to use Zonemaster’s GUI here, possibly with screenshots. I didn’t understand why this document mentioned (another) API until I read it, and understood that said API is not really an application programming interface, but just a collection of URL tricks for populating some of the inputs.
There was a problem hiding this comment.
A pointer to a work from OVH to provide such documentation: ovh/docs#3471
|
The I see three options:
How is the SUMMARY file created? If it is kept, it must be updated at each release. |
|
Under |
matsduf
left a comment
There was a problem hiding this comment.
I left a comment and some questions, and I see that more work must be done, but in general I think this is fine.
ghost
left a comment
There was a problem hiding this comment.
@marc-vanderwal Thirdly, one of the documents links to documentation generated by perldoc, hosted on metacpan.org. Maybe we could add this perldoc documentation in this documentation, if it’s at all feasible?
This would be a great idea indeed!
@matsduf 3. README files are created in every directory and they must contain a list of links to the files in the directory.
I was thinking about something similar. We could add to each TestPlan README file a subset of the "List of Defined Test Cases" array from the specifications/tests/README.md file with the TestPlan's test cases.
| @@ -0,0 +1,5 @@ | |||
| # Using the GUI | |||
|
|
|||
| * The [GUI API][API] | |||
There was a problem hiding this comment.
A pointer to a work from OVH to provide such documentation: ovh/docs#3471
| - [Zonemaster-Backend](installation/zonemaster-backend.md) | ||
| - [Zonemaster-GUI](installation/zonemaster-gui.md) | ||
| - [Docker](installation/docker.md) | ||
| - [Upgrade]() |
There was a problem hiding this comment.
I'll provide an update in a follow-up PR.
| @@ -0,0 +1,121 @@ | |||
| - [Installation](installation/README.md) | |||
There was a problem hiding this comment.
I'll remove the link in a follow-up PR.
Follow-up to zonemaster#1129 and zonemaster#1146
Purpose
This PR centralizes the documentation, putting together documentation files from across components into the main zonemaster/zonemaster repository. This will help browsing the documentation and allow at a later stage to publish it.
Context
Discussions at F2F 2022-06 and 2023-01.
Changes
Copy some documentation files to zonemaster/zonemaster (see commits).
New tree structure of docs/
How to test this PR
Further work
This is the first step of a bigger work that wants to centralize the Zonemaster documentation to then publish it on its own using mdbook.