Re: Proof of concept for Cassandra docs conversion
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 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. lor...@datastax.com > w. www.datastax.com > > > > On Thu, Jun 11, 2020 at 7:13 PM Anthony Grasso > 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 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 > > > 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 > > > 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
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. lor...@datastax.com w. www.datastax.com On Thu, Jun 11, 2020 at 7:13 PM Anthony Grasso 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 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 > > 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 > > 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
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 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 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 > > 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 > > 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
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 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 > 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 > 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
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 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 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
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 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 > > wrote: > > > I told the same to Lorina in person, +1 more fan > > > > On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie > > 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 > > 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
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 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 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
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 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
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 wrote: > I told the same to Lorina in person, +1 more fan > > On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie > 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 > 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
I told the same to Lorina in person, +1 more fan On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie 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 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
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 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) >
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)