How to decide where to land the documentation? 2 options:
- docs.openstack.com
We will not be publishing things under openstack.org
Understood
- docs.starlingx.io
This or something else under starlingx.io
Understood
[ OpenStack Documentation ] For each project we create source code directories to enable specific functionality:
<stx-project>/docs/ General Documentation
/doc
Yep, typo
<stx-project>/api-ref/ API Reference <stx-project>/api-guide/ API Guide <stx-project>/releasenotes/ Release Notes
yes
:)
[ docs.starlingx.io ]
<stx-project>/docs/ -> docs.openstack.org/<stx-project> <stx-project>/api-ref/ -> developer.openstack.org/api-ref/<stx- project> <stx-project>/api-guide/ -> developer.openstack.org/api-guide/<stx- project> <stx-project>/releasenotes/ -> docs.openstack.org/releasenotes/<stx-project>
FWIW OpenStack did some of the separation here due to the different teams responsible for the content. We may not have that need and want to stick to a simpler format with everything under a single site.
Let me get into the next level of detail with respect to our source code structure and theme: [ Structure: Option 1 ] Aligned to OpenStack project conventions <stx-project>/docs/ <stx-project>/api-ref/ <stx-project>/api-guide/ <stx-project>/releasenotes/ [ Structure: Option 2 ] <stx-project>/docs/source/ <stx-project>/docs/api-ref/ <stx-project>/docs/api-guide/ <stx-project>/docs/releasenotes/ [ Theme ] Do we have a short and long term goal with respect to the theme? I assume we continue using sphinx and about its theme we have the following options: - default - continue with openstackdocstheme - a custom starlingx?
[ docs.starlingx.io ]
Source code directory structure can be kept however, what could be the landing process since it will be out of OpenStack infrastructure?
We need to get the server set up for this (via OpenStack Infra team) and set up the publishing jobs to populate it
Understood, any example in mailing lists or through a gerrit review which requests a non OpenStack landing site to learn from and start with this activity?
How about the layout?
Option 1 <stx-project>/docs/ -> docs.starlingx.io/<stx-project> <stx-project>/api-ref/ -> docs.starlingx.io/api-ref/<stx-project> <stx-project>/api-guide/ -> docs.starlingx.io/api-guide/<stx-project> <stx-project>/releasenotes/ -> docs.starlingx.io/releasenotes/<stx-project>
I prefer this or something similar...
Landing layout then to be defined after we work with OpenStack Infra team.