[Starlingx-discuss] StarlingX Documentation Initial Template

[Arce Moreno, Abraham]

> > 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.