You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cassandra.apache.org by Lorina Poland <lo...@datastax.com> on 2020/06/10 18:20:40 UTC
Proof of concept for Cassandra docs conversion
Hello all!
Based on an earlier discussion about moving the OSS C* docs to
asciidoc, to allow more flexibility in maintaining the docs, I've done
a proof of concept about what it would take to accomplish a
conversion. I converted rSt files to asciidoc files using pandoc, did
some additional editing, and use antora (antora.org) as a static site
generator to build the docs. The result is here:
https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe
editing of the docs is NOT complete, but I completed enough to feel
confident that this process can be accomplished. Some YAML
configuration for antora was required, and I did a minimum of UI
configuration (added color banner, logo). Looking for feedback and
questions anyone may have.
Thanks,
Lorina Poland (DataStax tech writer)
Re: Proof of concept for Cassandra docs conversion
Posted by Lorina Poland <lo...@datastax.com>.
Thanks for the vote of confidence, Anthony! Yes, search can be integrated
into the antora SSG; I just haven't pursued that yet. Obviously a feature
that is needed.
Lorina
On Thu, Jun 11, 2020 at 7:13 PM Anthony Grasso <an...@gmail.com>
wrote:
> I agree as well. Nice work, Lorina!
>
> This POC is a really good start. It has a bit more of a modern feel to it.
> The navigation bar on the side makes the information very accessible. This
> is a must for technical documentation.
>
> Would it be possible to have a search bar somewhere on the site? I think
> this would be useful to allow a user to navigate quickly to something they
> know they are after e.g. a nodetool command or configuration setting.
>
> Kind regards,
>
> On Fri, 12 Jun 2020 at 02:02, Jon Haddad <jo...@jonhaddad.com> wrote:
>
> > Agreed. This is an awesome POC in a pretty short period of time.
> >
> > I suspect with a little polish and cleanup this will be an improvement
> over
> > the existing site in every way.
> >
> > Thanks for putting this together, Lorina!
> >
> > On Thu, Jun 11, 2020 at 7:36 AM Joshua McKenzie <jm...@apache.org>
> > wrote:
> >
> > > Left bar navigation and content navigation on top right are both
> > > aesthetically and usability-wise quite superior IMO (comparing to
> > >
> https://cassandra.apache.org/doc/latest/getting_started/configuring.html
> > ).
> > >
> > > I'm a fan.
> > >
> > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com>
> > wrote:
> > >
> > > > Hello all!
> > > >
> > > > Based on an earlier discussion about moving the OSS C* docs to
> > > > asciidoc, to allow more flexibility in maintaining the docs, I've
> done
> > > > a proof of concept about what it would take to accomplish a
> > > > conversion. I converted rSt files to asciidoc files using pandoc, did
> > > > some additional editing, and use antora (antora.org) as a static
> site
> > > > generator to build the docs. The result is here:
> > > >
> > > >
> > >
> >
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_getting-5Fstarted_configuring.html-23changing-2Dthe-2Dlocation-2Dof-2DdirectoriesThe&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=57qpHuofWcJzqnGIF_M7WxOaLaNAKs4buNLWOFM0vMs&s=wTEu0dtK7H2_LkcYq7Xxw2VjPDLl-QSVb4tScXcS6mk&e=
> > > > editing of the docs is NOT complete, but I completed enough to feel
> > > > confident that this process can be accomplished. Some YAML
> > > > configuration for antora was required, and I did a minimum of UI
> > > > configuration (added color banner, logo). Looking for feedback and
> > > > questions anyone may have.
> > > >
> > > > Thanks,
> > > >
> > > > Lorina Poland (DataStax tech writer)
> > > >
> > >
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Jon Haddad <jo...@jonhaddad.com>.
Wow, this is *really* nice.
* The live search is awesome
* Loving having the versions in the documentation dropdown
* The UI is much nicer than the current version
I think the CQL docs are the biggest unknown at this point. Very much
looking forward to that. I originally doubted it would be possible to
convert everything for 4.0, but I am very optimistic now!
On Wed, Jun 24, 2020 at 10:50 AM Lorina Poland <lo...@datastax.com> wrote:
> I just wanted to update everyone on the POC for the docs website:
> https://polandll.github.io/site/Cassandra/4.0/index.html
>
> I've added lunr search to the site, and (mostly finished) custom header and
> footer that matches the current site. I've also added a dummy 3.11 version
> (same source files as 4.0-rc5) to demonstrate having selectable doc
> versions. Still manually editing files, so yes - I know there are still
> pages messed up. And the Last/Next buttons - trying to figure out the
> implementation.
>
> But all comments appreciated and solicited.
> Thanks,
> Lorina
> Lorina Poland
> e. lorina@datastax.com
> w. www.datastax.com
>
>
>
> On Thu, Jun 11, 2020 at 7:13 PM Anthony Grasso <an...@gmail.com>
> wrote:
>
> > I agree as well. Nice work, Lorina!
> >
> > This POC is a really good start. It has a bit more of a modern feel to
> it.
> > The navigation bar on the side makes the information very accessible.
> This
> > is a must for technical documentation.
> >
> > Would it be possible to have a search bar somewhere on the site? I think
> > this would be useful to allow a user to navigate quickly to something
> they
> > know they are after e.g. a nodetool command or configuration setting.
> >
> > Kind regards,
> >
> > On Fri, 12 Jun 2020 at 02:02, Jon Haddad <jo...@jonhaddad.com> wrote:
> >
> > > Agreed. This is an awesome POC in a pretty short period of time.
> > >
> > > I suspect with a little polish and cleanup this will be an improvement
> > over
> > > the existing site in every way.
> > >
> > > Thanks for putting this together, Lorina!
> > >
> > > On Thu, Jun 11, 2020 at 7:36 AM Joshua McKenzie <jm...@apache.org>
> > > wrote:
> > >
> > > > Left bar navigation and content navigation on top right are both
> > > > aesthetically and usability-wise quite superior IMO (comparing to
> > > >
> > https://cassandra.apache.org/doc/latest/getting_started/configuring.html
> > > ).
> > > >
> > > > I'm a fan.
> > > >
> > > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com>
> > > wrote:
> > > >
> > > > > Hello all!
> > > > >
> > > > > Based on an earlier discussion about moving the OSS C* docs to
> > > > > asciidoc, to allow more flexibility in maintaining the docs, I've
> > done
> > > > > a proof of concept about what it would take to accomplish a
> > > > > conversion. I converted rSt files to asciidoc files using pandoc,
> did
> > > > > some additional editing, and use antora (antora.org) as a static
> > site
> > > > > generator to build the docs. The result is here:
> > > > >
> > > > >
> > > >
> > >
> >
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_getting-5Fstarted_configuring.html-23changing-2Dthe-2Dlocation-2Dof-2DdirectoriesThe&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=57qpHuofWcJzqnGIF_M7WxOaLaNAKs4buNLWOFM0vMs&s=wTEu0dtK7H2_LkcYq7Xxw2VjPDLl-QSVb4tScXcS6mk&e=
> > > > > editing of the docs is NOT complete, but I completed enough to feel
> > > > > confident that this process can be accomplished. Some YAML
> > > > > configuration for antora was required, and I did a minimum of UI
> > > > > configuration (added color banner, logo). Looking for feedback and
> > > > > questions anyone may have.
> > > > >
> > > > > Thanks,
> > > > >
> > > > > Lorina Poland (DataStax tech writer)
> > > > >
> > > >
> > >
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Lorina Poland <lo...@datastax.com>.
I just wanted to update everyone on the POC for the docs website:
https://polandll.github.io/site/Cassandra/4.0/index.html
I've added lunr search to the site, and (mostly finished) custom header and
footer that matches the current site. I've also added a dummy 3.11 version
(same source files as 4.0-rc5) to demonstrate having selectable doc
versions. Still manually editing files, so yes - I know there are still
pages messed up. And the Last/Next buttons - trying to figure out the
implementation.
But all comments appreciated and solicited.
Thanks,
Lorina
Lorina Poland
e. lorina@datastax.com
w. www.datastax.com
On Thu, Jun 11, 2020 at 7:13 PM Anthony Grasso <an...@gmail.com>
wrote:
> I agree as well. Nice work, Lorina!
>
> This POC is a really good start. It has a bit more of a modern feel to it.
> The navigation bar on the side makes the information very accessible. This
> is a must for technical documentation.
>
> Would it be possible to have a search bar somewhere on the site? I think
> this would be useful to allow a user to navigate quickly to something they
> know they are after e.g. a nodetool command or configuration setting.
>
> Kind regards,
>
> On Fri, 12 Jun 2020 at 02:02, Jon Haddad <jo...@jonhaddad.com> wrote:
>
> > Agreed. This is an awesome POC in a pretty short period of time.
> >
> > I suspect with a little polish and cleanup this will be an improvement
> over
> > the existing site in every way.
> >
> > Thanks for putting this together, Lorina!
> >
> > On Thu, Jun 11, 2020 at 7:36 AM Joshua McKenzie <jm...@apache.org>
> > wrote:
> >
> > > Left bar navigation and content navigation on top right are both
> > > aesthetically and usability-wise quite superior IMO (comparing to
> > >
> https://cassandra.apache.org/doc/latest/getting_started/configuring.html
> > ).
> > >
> > > I'm a fan.
> > >
> > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com>
> > wrote:
> > >
> > > > Hello all!
> > > >
> > > > Based on an earlier discussion about moving the OSS C* docs to
> > > > asciidoc, to allow more flexibility in maintaining the docs, I've
> done
> > > > a proof of concept about what it would take to accomplish a
> > > > conversion. I converted rSt files to asciidoc files using pandoc, did
> > > > some additional editing, and use antora (antora.org) as a static
> site
> > > > generator to build the docs. The result is here:
> > > >
> > > >
> > >
> >
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_getting-5Fstarted_configuring.html-23changing-2Dthe-2Dlocation-2Dof-2DdirectoriesThe&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=57qpHuofWcJzqnGIF_M7WxOaLaNAKs4buNLWOFM0vMs&s=wTEu0dtK7H2_LkcYq7Xxw2VjPDLl-QSVb4tScXcS6mk&e=
> > > > editing of the docs is NOT complete, but I completed enough to feel
> > > > confident that this process can be accomplished. Some YAML
> > > > configuration for antora was required, and I did a minimum of UI
> > > > configuration (added color banner, logo). Looking for feedback and
> > > > questions anyone may have.
> > > >
> > > > Thanks,
> > > >
> > > > Lorina Poland (DataStax tech writer)
> > > >
> > >
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Anthony Grasso <an...@gmail.com>.
I agree as well. Nice work, Lorina!
This POC is a really good start. It has a bit more of a modern feel to it.
The navigation bar on the side makes the information very accessible. This
is a must for technical documentation.
Would it be possible to have a search bar somewhere on the site? I think
this would be useful to allow a user to navigate quickly to something they
know they are after e.g. a nodetool command or configuration setting.
Kind regards,
On Fri, 12 Jun 2020 at 02:02, Jon Haddad <jo...@jonhaddad.com> wrote:
> Agreed. This is an awesome POC in a pretty short period of time.
>
> I suspect with a little polish and cleanup this will be an improvement over
> the existing site in every way.
>
> Thanks for putting this together, Lorina!
>
> On Thu, Jun 11, 2020 at 7:36 AM Joshua McKenzie <jm...@apache.org>
> wrote:
>
> > Left bar navigation and content navigation on top right are both
> > aesthetically and usability-wise quite superior IMO (comparing to
> > https://cassandra.apache.org/doc/latest/getting_started/configuring.html
> ).
> >
> > I'm a fan.
> >
> > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com>
> wrote:
> >
> > > Hello all!
> > >
> > > Based on an earlier discussion about moving the OSS C* docs to
> > > asciidoc, to allow more flexibility in maintaining the docs, I've done
> > > a proof of concept about what it would take to accomplish a
> > > conversion. I converted rSt files to asciidoc files using pandoc, did
> > > some additional editing, and use antora (antora.org) as a static site
> > > generator to build the docs. The result is here:
> > >
> > >
> >
> https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe
> > > editing of the docs is NOT complete, but I completed enough to feel
> > > confident that this process can be accomplished. Some YAML
> > > configuration for antora was required, and I did a minimum of UI
> > > configuration (added color banner, logo). Looking for feedback and
> > > questions anyone may have.
> > >
> > > Thanks,
> > >
> > > Lorina Poland (DataStax tech writer)
> > >
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Jon Haddad <jo...@jonhaddad.com>.
Agreed. This is an awesome POC in a pretty short period of time.
I suspect with a little polish and cleanup this will be an improvement over
the existing site in every way.
Thanks for putting this together, Lorina!
On Thu, Jun 11, 2020 at 7:36 AM Joshua McKenzie <jm...@apache.org>
wrote:
> Left bar navigation and content navigation on top right are both
> aesthetically and usability-wise quite superior IMO (comparing to
> https://cassandra.apache.org/doc/latest/getting_started/configuring.html).
>
> I'm a fan.
>
> On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com> wrote:
>
> > Hello all!
> >
> > Based on an earlier discussion about moving the OSS C* docs to
> > asciidoc, to allow more flexibility in maintaining the docs, I've done
> > a proof of concept about what it would take to accomplish a
> > conversion. I converted rSt files to asciidoc files using pandoc, did
> > some additional editing, and use antora (antora.org) as a static site
> > generator to build the docs. The result is here:
> >
> >
> https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe
> > editing of the docs is NOT complete, but I completed enough to feel
> > confident that this process can be accomplished. Some YAML
> > configuration for antora was required, and I did a minimum of UI
> > configuration (added color banner, logo). Looking for feedback and
> > questions anyone may have.
> >
> > Thanks,
> >
> > Lorina Poland (DataStax tech writer)
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Lorina Poland <lo...@datastax.com>.
Just a note, to emphasize - I did not complete the conversion of all the
files from rSt to asciidoc yet. I wanted feedback that this direction
seemed acceptable to everyone.
Sylvain, I'll check out the tool you mention and see if it provides better
translation. A one-time conversion effort is just that, though; rSt has
some decided quirks that make the conversion to any other markup
challenging.
Thanks for the feedback!
Lorina
On Thu, Jun 11, 2020 at 8:13 AM Sylvain Lebresne <le...@gmail.com> wrote:
> Agreed the navigation is nicer.
>
> The content rst conversion is however far from perfect, especially in the
> CQL parts. The grammar parts are all broken, most tables are really weird
> (example:
>
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_types.html&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=HsSPj9vYYbc2vVPNFrAqnMLZAz2ViLNZhPvU3cP1dCc&s=v5p3jTSLjuG_8QlzsBv2bqNKV0OM7v2vrVfN85YAduc&e=
> )
> and we lost almost all linking in those parts.
>
> I think that's up to pandoc not handling rst too well, and while that could
> be fixed manually, it's going to be some work. So I'd suggest giving a shot
> at
> https://urldefense.proofpoint.com/v2/url?u=https-3A__pypi.org_project_sphinx-2Dasciidoc_&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=HsSPj9vYYbc2vVPNFrAqnMLZAz2ViLNZhPvU3cP1dCc&s=Sk4bb6rmPcdu_CsF426Ta-p5mwkcJirmv5hsNf2FZxo&e=
> as an alternative. I haven't
> tested it, but it supposedly exists to be a better converter than pandoc
> and it may save some of that manual work.
> --
> Sylvain
>
>
> On Thu, Jun 11, 2020 at 4:45 PM Ekaterina Dimitrova <e.dimitrova@gmail.com
> >
> wrote:
>
> > I told the same to Lorina in person, +1 more fan
> >
> > On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie <jm...@apache.org>
> > wrote:
> >
> > > Left bar navigation and content navigation on top right are both
> > > aesthetically and usability-wise quite superior IMO (comparing to
> > >
> https://cassandra.apache.org/doc/latest/getting_started/configuring.html
> > ).
> > >
> > > I'm a fan.
> > >
> > > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com>
> > wrote:
> > >
> > > > Hello all!
> > > >
> > > > Based on an earlier discussion about moving the OSS C* docs to
> > > > asciidoc, to allow more flexibility in maintaining the docs, I've
> done
> > > > a proof of concept about what it would take to accomplish a
> > > > conversion. I converted rSt files to asciidoc files using pandoc, did
> > > > some additional editing, and use antora (antora.org) as a static
> site
> > > > generator to build the docs. The result is here:
> > > >
> > > >
> > >
> >
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_getting-5Fstarted_configuring.html-23changing-2Dthe-2Dlocation-2Dof-2DdirectoriesThe&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=HsSPj9vYYbc2vVPNFrAqnMLZAz2ViLNZhPvU3cP1dCc&s=wrHgAx24wI9dskwFiDgg8jtb__tc9HLjRDaCeerk7XE&e=
> > > > editing of the docs is NOT complete, but I completed enough to feel
> > > > confident that this process can be accomplished. Some YAML
> > > > configuration for antora was required, and I did a minimum of UI
> > > > configuration (added color banner, logo). Looking for feedback and
> > > > questions anyone may have.
> > > >
> > > > Thanks,
> > > >
> > > > Lorina Poland (DataStax tech writer)
> > > >
> > >
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Sylvain Lebresne <le...@gmail.com>.
Agreed the navigation is nicer.
The content rst conversion is however far from perfect, especially in the
CQL parts. The grammar parts are all broken, most tables are really weird
(example:
https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/types.html)
and we lost almost all linking in those parts.
I think that's up to pandoc not handling rst too well, and while that could
be fixed manually, it's going to be some work. So I'd suggest giving a shot
at https://pypi.org/project/sphinx-asciidoc/ as an alternative. I haven't
tested it, but it supposedly exists to be a better converter than pandoc
and it may save some of that manual work.
--
Sylvain
On Thu, Jun 11, 2020 at 4:45 PM Ekaterina Dimitrova <e....@gmail.com>
wrote:
> I told the same to Lorina in person, +1 more fan
>
> On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie <jm...@apache.org>
> wrote:
>
> > Left bar navigation and content navigation on top right are both
> > aesthetically and usability-wise quite superior IMO (comparing to
> > https://cassandra.apache.org/doc/latest/getting_started/configuring.html
> ).
> >
> > I'm a fan.
> >
> > On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com>
> wrote:
> >
> > > Hello all!
> > >
> > > Based on an earlier discussion about moving the OSS C* docs to
> > > asciidoc, to allow more flexibility in maintaining the docs, I've done
> > > a proof of concept about what it would take to accomplish a
> > > conversion. I converted rSt files to asciidoc files using pandoc, did
> > > some additional editing, and use antora (antora.org) as a static site
> > > generator to build the docs. The result is here:
> > >
> > >
> >
> https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe
> > > editing of the docs is NOT complete, but I completed enough to feel
> > > confident that this process can be accomplished. Some YAML
> > > configuration for antora was required, and I did a minimum of UI
> > > configuration (added color banner, logo). Looking for feedback and
> > > questions anyone may have.
> > >
> > > Thanks,
> > >
> > > Lorina Poland (DataStax tech writer)
> > >
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Ekaterina Dimitrova <e....@gmail.com>.
I told the same to Lorina in person, +1 more fan
On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie <jm...@apache.org> wrote:
> Left bar navigation and content navigation on top right are both
> aesthetically and usability-wise quite superior IMO (comparing to
> https://cassandra.apache.org/doc/latest/getting_started/configuring.html).
>
> I'm a fan.
>
> On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com> wrote:
>
> > Hello all!
> >
> > Based on an earlier discussion about moving the OSS C* docs to
> > asciidoc, to allow more flexibility in maintaining the docs, I've done
> > a proof of concept about what it would take to accomplish a
> > conversion. I converted rSt files to asciidoc files using pandoc, did
> > some additional editing, and use antora (antora.org) as a static site
> > generator to build the docs. The result is here:
> >
> >
> https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe
> > editing of the docs is NOT complete, but I completed enough to feel
> > confident that this process can be accomplished. Some YAML
> > configuration for antora was required, and I did a minimum of UI
> > configuration (added color banner, logo). Looking for feedback and
> > questions anyone may have.
> >
> > Thanks,
> >
> > Lorina Poland (DataStax tech writer)
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Joshua McKenzie <jm...@apache.org>.
Left bar navigation and content navigation on top right are both
aesthetically and usability-wise quite superior IMO (comparing to
https://cassandra.apache.org/doc/latest/getting_started/configuring.html).
I'm a fan.
On Wed, Jun 10, 2020 at 2:21 PM Lorina Poland <lo...@datastax.com> wrote:
> Hello all!
>
> Based on an earlier discussion about moving the OSS C* docs to
> asciidoc, to allow more flexibility in maintaining the docs, I've done
> a proof of concept about what it would take to accomplish a
> conversion. I converted rSt files to asciidoc files using pandoc, did
> some additional editing, and use antora (antora.org) as a static site
> generator to build the docs. The result is here:
>
> https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe
> editing of the docs is NOT complete, but I completed enough to feel
> confident that this process can be accomplished. Some YAML
> configuration for antora was required, and I did a minimum of UI
> configuration (added color banner, logo). Looking for feedback and
> questions anyone may have.
>
> Thanks,
>
> Lorina Poland (DataStax tech writer)
>
Re: Proof of concept for Cassandra docs conversion
Posted by Lorina Poland <lo...@datastax.com>.
Thanks for the feedback, Murukesh! As I mentioned, the editing to fix all
the formatting is not completed, but I wanted to share the work so far to
get feedback.
I have not tailored most of the styling of the website. I literally used
the default antora UI, only changing the banner to green and adding the
Cassandra logo. So all the navigation can use some additional work; in
fact, I only created the navigation files for 2-3 of the sections. Same
with the breadcrumbs, more work to make it production-worthy. (But aren't
those breadcrumbs cool?!)
I have tried a few different conversions. I believe I did try rSt-> HTML ->
asciidoc, but I'll check my files again.
I have 4 separate sources of files used to create this POC, some local on
my Macbook, and some publicly available:
So, right now, the pieces of the process are in 4 locations:
1. docs-site (local - where I run antora)
2. a clone of https://gitlab.com/antora/antora-ui-default (local - where I
made minimal look and feel changes)
3.
https://github.com/polandll/cassandra-examples/tree/master/rst-to-asciidoc-tests/ASCIIDOC
(where
I am storing the asciidoc files that I’ve converted/editing)
4. https://github.com/polandll/polandll.github.io (where the prototype
docs website
is located)
Feel free to check out the *.adoc files in the 3rd resource, but know that
I am actively making changes there.
Thanks,
Lorina
On Thu, Jun 11, 2020 at 8:15 AM Murukesh Mohanan <mu...@gmail.com>
wrote:
> Is the AsciiDoc source also on GitHub?
>
> Some things that I noticed:
>
> - The FAQ sidebar navigation is great! The TOC list at the top isn't
> needed at all now.
> - In the breadcrumb trail (e.g., ASCIIDOC_POC > Cassandra > FAQ, or
> ASCIIDOC_POC > Cassandra Documentation > Glossary), *Cassandra* in the
> Cassandra pages isn't a link but Cassandra Documentation is.
> - Some of the code blocks are off (e.g,
>
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_indexes.html-23create-2Dindex-2Dstatement&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU&s=Eg_JbhzOrbE1c5RgXi1UHjOQ-Np-uTmzDyPukPwWvfE&e=
> ,
>
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_mvs.html&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU&s=emL2s3ZZkCU5-L2Zg0-mlYKamtcCh2NkqVSu5Wn41Ss&e=
> )
> - Pandoc clobbered the "MV select" part in
>
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_cql_mvs.html&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU&s=emL2s3ZZkCU5-L2Zg0-mlYKamtcCh2NkqVSu5Wn41Ss&e=
> into the preceding note.
>
> I wonder if it will be worth it to try rSt -> HTML (using the current build
> tools) -> AsciiDoc (using Pandoc).
>
> Yours,
> Murukesh Mohanan
>
>
> On Thu, 11 Jun 2020 at 03:21, Lorina Poland <lo...@datastax.com> wrote:
>
> > Hello all!
> >
> > Based on an earlier discussion about moving the OSS C* docs to
> > asciidoc, to allow more flexibility in maintaining the docs, I've done
> > a proof of concept about what it would take to accomplish a
> > conversion. I converted rSt files to asciidoc files using pandoc, did
> > some additional editing, and use antora (antora.org) as a static site
> > generator to build the docs. The result is here:
> >
> >
> https://urldefense.proofpoint.com/v2/url?u=https-3A__polandll.github.io_site_ASCIIDOC-5FPOC_4.0_cassandra_getting-5Fstarted_configuring.html-23changing-2Dthe-2Dlocation-2Dof-2DdirectoriesThe&d=DwIBaQ&c=adz96Xi0w1RHqtPMowiL2g&r=bL2UpIjL4Mm1mCbqWThJUiPD-CmTXMALsIT2Ta-KfGk&m=8C0qNdZj2XHZ-aA4ZjwgWI_Y6Nael_kjR7Wp-6CiOLU&s=a_fQx4FtvGnSkExAfzZM2BZAiaOmEeo9EA8DXjAYKz4&e=
> > editing of the docs is NOT complete, but I completed enough to feel
> > confident that this process can be accomplished. Some YAML
> > configuration for antora was required, and I did a minimum of UI
> > configuration (added color banner, logo). Looking for feedback and
> > questions anyone may have.
> >
> > Thanks,
> >
> > Lorina Poland (DataStax tech writer)
> >
>
Re: Proof of concept for Cassandra docs conversion
Posted by Murukesh Mohanan <mu...@gmail.com>.
Is the AsciiDoc source also on GitHub?
Some things that I noticed:
- The FAQ sidebar navigation is great! The TOC list at the top isn't
needed at all now.
- In the breadcrumb trail (e.g., ASCIIDOC_POC > Cassandra > FAQ, or
ASCIIDOC_POC > Cassandra Documentation > Glossary), *Cassandra* in the
Cassandra pages isn't a link but Cassandra Documentation is.
- Some of the code blocks are off (e.g,
https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/indexes.html#create-index-statement,
https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/mvs.html)
- Pandoc clobbered the "MV select" part in
https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/cql/mvs.html
into the preceding note.
I wonder if it will be worth it to try rSt -> HTML (using the current build
tools) -> AsciiDoc (using Pandoc).
Yours,
Murukesh Mohanan
On Thu, 11 Jun 2020 at 03:21, Lorina Poland <lo...@datastax.com> wrote:
> Hello all!
>
> Based on an earlier discussion about moving the OSS C* docs to
> asciidoc, to allow more flexibility in maintaining the docs, I've done
> a proof of concept about what it would take to accomplish a
> conversion. I converted rSt files to asciidoc files using pandoc, did
> some additional editing, and use antora (antora.org) as a static site
> generator to build the docs. The result is here:
>
> https://polandll.github.io/site/ASCIIDOC_POC/4.0/cassandra/getting_started/configuring.html#changing-the-location-of-directoriesThe
> editing of the docs is NOT complete, but I completed enough to feel
> confident that this process can be accomplished. Some YAML
> configuration for antora was required, and I did a minimum of UI
> configuration (added color banner, logo). Looking for feedback and
> questions anyone may have.
>
> Thanks,
>
> Lorina Poland (DataStax tech writer)
>