> I never suggested changing the currently generated documentation and said explicitly that this thread is about some additional pages (home page, download page etc.).
This is already clear to me (if thats who you were addressing). > Writing these additional pages (home page, download page etc.) as markdown files from which we generate HTML, etc. using sbt-paradox is a valid solution. There are other ways to generate these additional pages (home page, download page etc.). There are a number of existing contributors to Pekko who would be able to use the sbt-paradox approach. If anyone has a real love for an alternative approach, they may end up owning that solution - because we may not have many other contributors who are familiar with that alternative approach. I don't have anything necessarily against sbt-paradox, but judging from how it's designed it doesn't seem the best suited for landing pages in the sense that it has more complexity than necessary, also do note that the people that might work on the landing page isn't necessarily going to be the same set of people that are ultra familiar with paradox/sbt and ithe like. The other reason why I suggested the alternatives is because they are specifically designed for micro-sites/landing pages (sbt-microsite in particular is used for a huge portion of landing pages for OSS Scala projects, much more than sbt-paradox which generally speaking was used for mainly for lightbend projects). The other main point I made on the github issue is that the majority of the work will be generating a landing page with branding/design and hence sbt-paradox is kind of a distraction here. > We could have a hybrid approach. We could get basic versions of the home page and download page created with markdown and sbt-paradox. Someone else could create a nicer looking alternative set of pages and we can switch over to those when they are ready. Agreed, I also suggested this > To unblock this discussion which is one of the blockers for getting a release done, could I suggest taking a vote on using the markdown/sbt-paradox approach as an initial solution? To reiterate, I am not ruling out that an alternative nicer solution could be used later. Sure, go ahead. If we are just going to reuse the current material theme that is being used for docs its minimal effort and then later on we can explore other options (also in conjunction with making a nice landing page). On Mon, Mar 20, 2023 at 6:36 PM PJ Fanning <[email protected]> wrote: > I never suggested changing the currently generated documentation and > said explicitly that this thread is about some additional pages (home > page, download page etc.). > > Writing these additional pages (home page, download page etc.) as > markdown files from which we generate HTML, etc. using sbt-paradox is > a valid solution. There are other ways to generate these additional > pages (home page, download page etc.). There are a number of existing > contributors to Pekko who would be able to use the sbt-paradox > approach. If anyone has a real love for an alternative approach, they > may end up owning that solution - because we may not have many other > contributors who are familiar with that alternative approach. > > We could have a hybrid approach. We could get basic versions of the > home page and download page created with markdown and sbt-paradox. > Someone else could create a nicer looking alternative set of pages and > we can switch over to those when they are ready. > > To unblock this discussion which is one of the blockers for getting a > release done, could I suggest taking a vote on using the > markdown/sbt-paradox approach as an initial solution? To reiterate, I > am not ruling out that an alternative nicer solution could be used > later. > > On Mon, 20 Mar 2023 at 16:12, Matthew Benedict de Detrich > <[email protected]> wrote: > > > > We are talking about the host site which would be on pekko.apache.org, > not > > the documentation, documentation is already handled with sbt-paradox. > It's > > meant to be a nice landing page that will point to docs that are > generated > > by sbt-paradox. > > > > On Mon, Mar 20, 2023 at 2:58 PM Claude Warren, Jr > > <[email protected]> wrote: > > > > > Is this the website at pekko.apache.org or are you talking about the > java > > > doc and equivalent? > > > > > > Do we have anybody who has expertise in documentation development? > > > > > > On Wed, Mar 1, 2023 at 12:08 PM Matthew Benedict de Detrich > > > <[email protected]> wrote: > > > > > > > Previous discussion/s on this > > > > > > > > https://github.com/apache/incubator-pekko-site/pull/4 > > > > https://lists.apache.org/thread/lzfkmq6k6y9t02y4o97jmcgnzxqcp4kh > > > > > > > > I think this would be a good time to discuss what software we should > use > > > to > > > > generate our microsite at https://pekko.apache.org/ > > > > > > > > Suggestions that have already been made > > > > > > > > * Paradox: https://github.com/lightbend/paradox (we use this > currently > > > for > > > > docs and there is a current setup for it, see previously mentioned > PR) > > > > * sbt-microsites: https://github.com/47degrees/sbt-microsites (uses > > > Jekyll > > > > under the hood but wraps it in sbt which is the same build tool that > is > > > > used for all of the other Pekko projects) > > > > * https://github.com/planet42/Laika: Completely new design for > > > microsites, > > > > used somewhat in Scala projects. Also works with sbt > > > > * https://infra.apache.org/asf-pelican.html Used by Apache projects > > > > > > > > I am personally leaning towards either Paradox or sbt-microsites. My > > > > personal view on this is that while there are other technologies like > > > > pelican which have historically been used with Apache, to me keeping > the > > > > number of tech stacks/build tools in the Pekko ecosystem has higher > > > > priority and both of these projects use the exact same build tool > that > > > > Pekko libraries do. > > > > > > > > Ontop of this sbt-paradox is currently being used to generate our > docs > > > for > > > > our various modules, although it does appear to be more catered for > doc > > > > generated than microsites (I don't know how significant the > difference is > > > > between the two). > > > > -- > > > > > > > > Matthew de Detrich > > > > > > > > *Aiven Deutschland GmbH* > > > > > > > > Immanuelkirchstraße 26, 10405 Berlin > > > > > > > > Amtsgericht Charlottenburg, HRB 209739 B > > > > > > > > Geschäftsführer: Oskari Saarenmaa & Hannu Valtonen > > > > > > > > *m:* +491603708037 > > > > > > > > *w:* aiven.io *e:* [email protected] > > > > > > > > > > > > > -- > > > > Matthew de Detrich > > > > *Aiven Deutschland GmbH* > > > > Immanuelkirchstraße 26, 10405 Berlin > > > > Amtsgericht Charlottenburg, HRB 209739 B > > > > Geschäftsführer: Oskari Saarenmaa & Hannu Valtonen > > > > *m:* +491603708037 > > > > *w:* aiven.io *e:* [email protected] > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- Matthew de Detrich *Aiven Deutschland GmbH* Immanuelkirchstraße 26, 10405 Berlin Amtsgericht Charlottenburg, HRB 209739 B Geschäftsführer: Oskari Saarenmaa & Hannu Valtonen *m:* +491603708037 *w:* aiven.io *e:* [email protected]
