Hi, Replying to this thread as I started working on this.
- The automatic docs conversion from asciidoc to markdown is not straightforward because of the Paradox directives. It requires substantial manual work which will be needed anyway to update the Akka references to Pekko. - I have opened a PR #26 to set up a minimal build.sbt with Paradox config. To summarize on how to proceed: 1. Remove all unnecessary content from the guide (i.e.: Akka Cloud Platform + Telemetry). This also helps to speed up point 2. 2. Start the gradual conversion from Asciidoc to Paradox markdown + Remove the Akka reference (asciidoc and Paradox build can live side by side in the repo) 3. Start the conversion of the docs-source/docs/modules/microservices-tutorial and the docs-source/docs/modules/how-to source code 4. Remove all the asciidoc build-related files 5. Update the publishing guide Let me know your thoughts. Thanks. Samuele Il giorno ven 28 apr 2023 alle ore 15:48 Sam Byng <[email protected]> ha scritto: > I think this is probably the ideal long term situation. I would say that > we should do this now too. > > I assume this will require the following - anything else? > > - Docs conversion from asciidoc to markdown (potential bugs / features > lost introduced during conversion) > Seems like there's a CLI tool for this here: > https://github.com/opendevise/downdoc > > - Update of codebase with a build.sbt file + paradox setup code / config > etc. > > - Update to use the pekko guide UI instead of the lightbend UI > > - Strip out the current antora / asciidoctor code. > > - Update the manual publishing guide: > https://github.com/apache/incubator-pekko-site/wiki/Manual-Publishing > > Pros: Consistent approach, Easily get the Apache Pekko UI in, Using a > build tool that we control. > Cons: More work to get platform guide out. Bugs converting docs that will > need ironing out. > > -Sam > > -----Original Message----- > From: PJ Fanning <[email protected]> > Sent: Friday, April 28, 2023 11:44 AM > To: [email protected] > Subject: [EXTERNAL] Re: [DISCUSS] Publishing and hosting the > pekko-platform-guide > > Any chance we could make the doc build use the pekko-sbt-paradox plugin > like we use elsewhere? > > On Thu, 27 Apr 2023 at 19:28, Sam Byng <[email protected]> > wrote: > > > > Hi all, > > > > I'm looking at https://github.com/apache/incubator-pekko/issues/244 and > would like to discuss how we will publish and host the pekko platform > guides. > > > > > > On publishing releases: > > In akka the guide was 'published via tech hub via a webhook'. > > I'm not familiar with tech hub / I don't have expertise here but perhaps > we will want to do something more similar to the pekko-sites? > > > > On hosting: > > In akka, there was a separate website for the akka platform guide ( > > https://deve/ > > loper.lightbend.com%2Fdocs%2Fakka-guide&data=05%7C01%7Csambyng%40micro > > soft.com%7C6a08ee46d9a44e95f54a08db47d59074%7C72f988bf86f141af91ab2d7c > > d011db47%7C1%7C0%7C638182754825387733%7CUnknown%7CTWFpbGZsb3d8eyJWIjoi > > MC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7 > > C%7C&sdata=7JVRAvKSFQNHncyrp1U7FzC5CXDUjcRiW8dWA0QsHYA%3D&reserved=0 ) > > vs the akka docs ( > > https://doc/. > > akka.io%2Fdocs%2Fakka%2Fcurrent%2Ftyped%2Fguide%2F&data=05%7C01%7Csamb > > yng%40microsoft.com%7C6a08ee46d9a44e95f54a08db47d59074%7C72f988bf86f14 > > 1af91ab2d7cd011db47%7C1%7C0%7C638182754825387733%7CUnknown%7CTWFpbGZsb > > 3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D% > > 7C3000%7C%7C%7C&sdata=XrwXrAZWKlF9kjzEV1Ism0w1d%2FHmbx3FGrUm%2FISX83k% > > 3D&reserved=0) Do we want something similar here or do we want to > > bundle the platform guide into pekko.apache.org ? > > > > On the platform guide UI 'theme': > > In akka, the lightbend antora-supplemental theme was used. Do we still > want this? > > [https://git/ > > hub.com%2Fapache%2Fincubator-pekko-platform-guide%2Fblob%2Fmain%2Fdocs > > -source%2Fsite.yml%23L15&data=05%7C01%7Csambyng%40microsoft.com%7C6a08 > > ee46d9a44e95f54a08db47d59074%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C > > 0%7C638182754825387733%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJ > > QIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=pW3q > > U9FCdSKo2o9ABggJ75dAqEmBgWmD9GhFVrImtno%3D&reserved=0] > > > > > > Please let me know your thoughts. In the meantime, Samuele and I will be > raising PRs to convert the docs themselves. > > > > > > Many thanks > > > > Sam > > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] For additional > commands, e-mail: [email protected] > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
