Create dedicated subdomain for developer docs

[andrewdavidwong]

We have an excellent and beautiful set of autogenerated docs for qubes-core-admin here:

https://qubes-core-admin.readthedocs.org/en/latest/

From a UX perspective, it may be desirable to somehow integrate these docs (without harming their excellence and beauty, of course) with our main set of docs here:

https://www.qubes-os.org/doc/

CC: @bnvk

[marmarek]

https://www.qubes-os.org/doc/ is probably not the best place for strictly developer documentation. Also the whole point about readthedocs.org usage is they render it (and track changes). On the other hand, we may (and probably should) add a link to it somewhere. It is also possible to attach custom domain to it (for example devel-doc.qubes-os.org, or something). Still - not sure if we need it, but it is possible.

[marmarek]

https://www.qubes-os.org/doc/ is probably not the best place for strictly developer documentation. Also the whole point about readthedocs.org usage is they render it (and track changes). On the other hand, we may (and probably should) add a link to it somewhere. It is also possible to attach custom domain to it (for example devel-doc.qubes-os.org, or something). Still - not sure if we need it, but it is possible.

[andrewdavidwong]

Ok, but currently the rest of our developer docs already reside at https://www.qubes-os.org/doc/#for-developers . ISTM that all the developer docs should be in one place (even if that place is not https://www.qubes-os.org/doc/). So, would it make sense to convert this issue into the more general one of having separate developer documentation?

[andrewdavidwong]

Ok, but currently the rest of our developer docs already reside at https://www.qubes-os.org/doc/#for-developers . ISTM that all the developer docs should be in one place (even if that place is not https://www.qubes-os.org/doc/). So, would it make sense to convert this issue into the more general one of having separate developer documentation?

[marmarek]

Actually developer documentation is here: https://www.qubes-os.org/doc/system-doc/
Anyway, jekyll can't render sphinx documentation (or anything else based on python docstrings), so this part must be somehow separate. We can render it to html and commit as static files, but it would be out of sync most of the time...

[marmarek]

Actually developer documentation is here: https://www.qubes-os.org/doc/system-doc/
Anyway, jekyll can't render sphinx documentation (or anything else based on python docstrings), so this part must be somehow separate. We can render it to html and commit as static files, but it would be out of sync most of the time...

[andrewdavidwong]

Actually developer documentation is here: https://www.qubes-os.org/doc/system-doc/

Well, that's just one item under the whole "For Developers" section...

Anyway, jekyll can't render sphinx documentation (or anything else based on python docstrings), so this part must be somehow separate.

Right. That's why I agree that it makes sense to have that documentation on a separate subdomain (e.g., dev.qubes-os.org), like you said. However, if we create dev.qubes-os.org and start hosting the sphinx documentation there, wouldn't it also make sense to move the existing developer documentation there too? That's all I'm suggesting.

We can render it to html and commit as static files, but it would be out of sync most of the time...

This sounds like it would just create more headaches down the road by deautomating something that's already automated. It seems like we should avoid this at all costs.

[andrewdavidwong]

Actually developer documentation is here: https://www.qubes-os.org/doc/system-doc/

Well, that's just one item under the whole "For Developers" section...

Anyway, jekyll can't render sphinx documentation (or anything else based on python docstrings), so this part must be somehow separate.

Right. That's why I agree that it makes sense to have that documentation on a separate subdomain (e.g., dev.qubes-os.org), like you said. However, if we create dev.qubes-os.org and start hosting the sphinx documentation there, wouldn't it also make sense to move the existing developer documentation there too? That's all I'm suggesting.

We can render it to html and commit as static files, but it would be out of sync most of the time...

This sounds like it would just create more headaches down the road by deautomating something that's already automated. It seems like we should avoid this at all costs.

[andrewdavidwong]

Well, that's just one item under the whole "For Developers" section...

Just to clarify: I realize that most of the developer documentation is there, and that it contains many pages. But it's still currently just one bullet point under the "For Developers" section, which includes many other things for developers. That's why I initially linked to the whole "For Developers" section.

[andrewdavidwong]

Well, that's just one item under the whole "For Developers" section...

Just to clarify: I realize that most of the developer documentation is there, and that it contains many pages. But it's still currently just one bullet point under the "For Developers" section, which includes many other things for developers. That's why I initially linked to the whole "For Developers" section.

[bnvk]

Given the sphinx build issue, I agree with @axon-qubes is the best approach.

However, if we create dev.qubes-os.org and start hosting the sphinx documentation there, wouldn't it also make sense to move the existing developer documentation there too? That's all I'm suggesting.

[bnvk]

Given the sphinx build issue, I agree with @axon-qubes is the best approach.

However, if we create dev.qubes-os.org and start hosting the sphinx documentation there, wouldn't it also make sense to move the existing developer documentation there too? That's all I'm suggesting.

[woju]

Just two points on this: 1) We keep manpages of qvm-tools in the repo for obvious reasons. Those aren't "developer" documentation and would be nice to integrate with user-facing webpage. We had it that way when we had Trac. Currently we render them using sphinx. 2) There are different kinds of "developer" documentation. The one on readthedocs is API documentation, subject to change whenever API changes, and has to be synchronised with specific version of respective component. It is created from repository. The other kind of documentation (like how to configure your qubes-devel VM or where we do keep our bug tracker) does not have (and probably should not) reside in any code repository.

[woju]

Just two points on this: 1) We keep manpages of qvm-tools in the repo for obvious reasons. Those aren't "developer" documentation and would be nice to integrate with user-facing webpage. We had it that way when we had Trac. Currently we render them using sphinx. 2) There are different kinds of "developer" documentation. The one on readthedocs is API documentation, subject to change whenever API changes, and has to be synchronised with specific version of respective component. It is created from repository. The other kind of documentation (like how to configure your qubes-devel VM or where we do keep our bug tracker) does not have (and probably should not) reside in any code repository.

[andrewdavidwong]

Thank you for clarifying that, @woju. How do you think we should handle the organization of these documents? If you and @marmarek think that things are fine as they currently are, I'm happy to close this issue and simply add an external link to the qubes-core-admin docs.

[andrewdavidwong]

Thank you for clarifying that, @woju. How do you think we should handle the organization of these documents? If you and @marmarek think that things are fine as they currently are, I'm happy to close this issue and simply add an external link to the qubes-core-admin docs.

[marmarek]

On Mon, Apr 25, 2016 at 02:09:08AM -0700, Axon wrote:

Thank you for clarifying that, @woju. How do you think we should handle the organization of these documents? If you and @marmarek think that things are fine as they currently are, I'm happy to close this issue and simply add an external link to the qubes-core-admin docs.

Since that is "only" about development, not yet released version, I'd go
that way for now.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

On Mon, Apr 25, 2016 at 02:09:08AM -0700, Axon wrote:

Thank you for clarifying that, @woju. How do you think we should handle the organization of these documents? If you and @marmarek think that things are fine as they currently are, I'm happy to close this issue and simply add an external link to the qubes-core-admin docs.

Since that is "only" about development, not yet released version, I'd go
that way for now.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[woju]

On Mon, Apr 25, 2016 at 02:09:08AM -0700, Axon wrote:

Thank you for clarifying that, @woju. How do you think we should
handle the organization of these documents? If you and @marmarek think
that things are fine as they currently are, I'm happy to close this
issue and simply add an external link to the qubes-core-admin docs.

I don't know. The API docs are fine (potential developers will manage),
however manpages could be integrated into qubes-os.org.

I don't know how the jekyll engine works so I don't have a solution. Can
you render RST with it? If so, we could add qubes-core-admin as yet
another submodule and render manpages from there. If not, we could
convert them somehow and keep those converted pages in separate
repo/submodule.

[woju]

On Mon, Apr 25, 2016 at 02:09:08AM -0700, Axon wrote:

Thank you for clarifying that, @woju. How do you think we should
handle the organization of these documents? If you and @marmarek think
that things are fine as they currently are, I'm happy to close this
issue and simply add an external link to the qubes-core-admin docs.

I don't know. The API docs are fine (potential developers will manage),
however manpages could be integrated into qubes-os.org.

I don't know how the jekyll engine works so I don't have a solution. Can
you render RST with it? If so, we could add qubes-core-admin as yet
another submodule and render manpages from there. If not, we could
convert them somehow and keep those converted pages in separate
repo/submodule.

[marmarek]

On Mon, Apr 25, 2016 at 02:19:30AM -0700, Wojtek Porczyk wrote:

I don't know how the jekyll engine works so I don't have a solution. Can
you render RST with it? If so, we could add qubes-core-admin as yet
another submodule and render manpages from there. If not, we could
convert them somehow and keep those converted pages in separate
repo/submodule.

There is already script for that in _utils/update-manpages. Currently
called manually from time to time, but it shouldn't be hard to automate
it somehow. Anyway IMHO it is really low priority, as manpages changes
aren't that often.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

On Mon, Apr 25, 2016 at 02:19:30AM -0700, Wojtek Porczyk wrote:

I don't know how the jekyll engine works so I don't have a solution. Can
you render RST with it? If so, we could add qubes-core-admin as yet
another submodule and render manpages from there. If not, we could
convert them somehow and keep those converted pages in separate
repo/submodule.

There is already script for that in _utils/update-manpages. Currently
called manually from time to time, but it shouldn't be hard to automate
it somehow. Anyway IMHO it is really low priority, as manpages changes
aren't that often.

Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?

[marmarek]

I'm not sure how to mix this. There is API documentation, strongly connected to specific source version and component. Stored with source code itself to prevent synchronization problems, in specific branches etc. Built using sphinx (the tool that extract documentation out of docstrings in the code).
And there is also generic developer documentation, like "how to submit a patch", or "how to build Qubes OS". The later is isn't connected to any specific source component. Additionally it is in different format (markdown, for jekyll), so can't be easily integrated. And I don't see a point in converting it one way or another. Especially because there are some blurry cases, like "how to create qrexec service" - is it developer, or user documentation?

[marmarek]

I'm not sure how to mix this. There is API documentation, strongly connected to specific source version and component. Stored with source code itself to prevent synchronization problems, in specific branches etc. Built using sphinx (the tool that extract documentation out of docstrings in the code).
And there is also generic developer documentation, like "how to submit a patch", or "how to build Qubes OS". The later is isn't connected to any specific source component. Additionally it is in different format (markdown, for jekyll), so can't be easily integrated. And I don't see a point in converting it one way or another. Especially because there are some blurry cases, like "how to create qrexec service" - is it developer, or user documentation?

[andrewdavidwong]

It sounds like trying to have all the different types of docs in a single "place" would require a lot of work right now. Probably not worth the UX benefit of having everything in a single domain. It might be good enough if we just have prominent links on each site pointing to each other, for now.

[andrewdavidwong]

It sounds like trying to have all the different types of docs in a single "place" would require a lot of work right now. Probably not worth the UX benefit of having everything in a single domain. It might be good enough if we just have prominent links on each site pointing to each other, for now.

[bnvk]

I bet if I were to spend a day of work tweaking the styling the themes of each documentation type and added a unified header that linked between all the types it would go a long way in helping things seem more cohesive and organized... something for down the road!

[bnvk]

I bet if I were to spend a day of work tweaking the styling the themes of each documentation type and added a unified header that linked between all the types it would go a long way in helping things seem more cohesive and organized... something for down the road!

[andrewdavidwong]

Current situation seems fine for now. Feel free to comment or re-open if you disagree.

[andrewdavidwong]

Current situation seems fine for now. Feel free to comment or re-open if you disagree.