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 <lebre...@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.dimitr...@gmail.com > > > wrote: > > > I told the same to Lorina in person, +1 more fan > > > > On Thu, 11 Jun 2020 at 10:36, Joshua McKenzie <jmcken...@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 <lor...@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) > > > > > > > > > >
