For me, it's ok to make the changes that you suggested and to come back later with a brand new proposal that may or may not use a different microsite build tool.
For me, there is also the open issue of what to do about the static files like the Pekko CSS used by our per-repo doc builds - described here: https://github.com/apache/incubator-pekko-sbt-paradox/issues/84 There may be some merit in trying to create a single CSS file that can be committed to the incubator-pekko-site repo instead of having separate CSS files for the home page(s) and the other docs - even if we apply some different styling. On Wed, 20 Dec 2023 at 15:26, Samuele Resca <[email protected]> wrote: > > Hi, > > I have experimented a bit with the capabilities of Paradox and produced a > design proposal for the homepage of Apache Pekko (https://pekko.apache.org) > available at the following PR: > https://github.com/apache/incubator-pekko-site/pull/47 > > Few notes: > > - The styling is specific for the homepage. Everything else in the docs > remains untouched. > - The actual content is mostly unchanged. > - The implementation relies on paradox. There has been some discussions on > using other technologies for the homepage[1][2]. While paradox makes the > job harder (specially in producing html), I think having a dedicated style > for the home is what we need for now. Improving the UI aspects of the home > from this point it should be easier. > - In order to add a dedicated style to the page, I need to override the the > `home.st` to include the styling. > > Let me know if it worth exploring more with other microsite technologies or > if you have any feedback on this design. > > [1] https://github.com/apache/incubator-pekko-site/pull/4 > [2] https://lists.apache.org/thread/fthn305vphk7l61gsldm2jyon7q7tz4w > > > On 2023/03/20 18:09:08 Matthew Benedict de Detrich 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.). > > > > 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] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
