apache
rewrite pekko-platform-guide to use pekko artifacts and to remove Akka refs
https://github.com/apache/incubator-pekko-platform-guide
This guide is referenced quite a bit from the main docs associated with this repo.
Edit: the doc refs from this repo have been temporarily removed which means that updating the pekko-platform-guide is not as urgent. See https://github.com/apache/incubator-pekko/commit/658e4bc4b0b9fd0305f435ab02c445a5344783aa
If and when the pekko-platform-guide is updated and published, we could revert that commit and tidy up the links to ensue they point to the right place (where the new pekko-platform-guide docs are published).
I think there's ~ 2d work here.
Key steps: 1. Investigate: Doc building + publishing process: What is the current process + Do we need to change anything here? 2. Investigate: Doc hosting platform: How will we host the website? Should we do anything to use the same platform as the other apache-pekko docs?
(i.e. put these docs onto https://pekko.apache.org/ / add these docs into apache/incubator-pekko-site: Apache pekko (github.com) )
- Converting the docs themselves to reference pekko and not akka.
1 and 2 require more investigation and discussion. 3 is pretty straight forward text changes and URL changes.
@sam-byng I've already removed the pekko doc links to the platform guide docs. See https://github.com/apache/incubator-pekko/commit/658e4bc4b0b9fd0305f435ab02c445a5344783aa
This makes this a nice-to-have as opposed to something that blocks a v1.0.0 release. If we do get the pekko-platform-guide fixed up though, we can easily add back the links.
On doc builds/tests
The current solution seems relatively straight forward:
locally: make html-author-mode start target/index.html
In github pipelines: current solution looks fine https://github.com/apache/incubator-pekko-platform-guide/blob/main/.github/workflows/build-and-test.yml
TODO So next steps here are to do the grunt work of converting the docs themselves. <- @sam-byng to take
It looks like test main branch builds were then deployed onto a test VM @ [email protected]
TODO: If we still use this workflow, this may need update to a pekko hosted VM. The exact owner of this etc needs discuss.
On publishing releases:
On akka, the The guide is published via tech hub via a webhook.
TODO: I don't have experience in this so I don't know what the correct process should be here. Possibly some crossover with https://github.com/apache/incubator-pekko-site
On hosting:
See point 2 above. If we decide to host @ pekko.apache.org/ then the discussions on mailing list of [DISCUSS] using a VM to serve the pekko.apache.org web site will be pertinent
Let's not assume that ASF will be able to host a VM. We might be able to but it may not be worth the cost for a non-profit org. If the gustav VM (or possible ASF equivalent) is an important part of someone being able to follow the instructions and run the samples, then we might need to consider whether this guide is a good thing for us.
doc pages can be hosted at https://pekko.apache.org/docs/platform-guide/current - or something similar.
If the gustav VM (or possible ASF equivalent) is an important part of someone being able to follow the instructions and run the samples, then we might need to consider whether this guide is a good thing for us.
AFIACT The use of the Gustav VM in this case is for test purposes. It looks like there's a long-lifetime akka.io website that is kept live and redeployed with the latest main whenever any main pipeline runs. This seems like a non-essential add-on that just lets devs easily view the current state of the docs on a server instead of needing to build locally.
So I propose just remove this since it looks like we won't want to use it.
I'd vote https://pekko.apache.org/docs/pekko-platform-guide/current , since the other modules are prefixed with pekko in https://pekko.apache.org/docs/ and the previous URL was @ akka-platform-guide
This has been de-prioritised to speed up the '1.0.0' release but it would still be great if someone could take it on.
@GauriPradeep the code is in https://github.com/apache/pekko-platform-guide. If you want to have a look, please feel free. I'm not expecting it to be an easy task. I think some Pekko changes have been merged but the Antora doc build is not something that we use anywhere else so it might be difficult to build the docs, let alone deploy them. If you can get to grips with what needs to be done, then it is probably useful to get this migration done. Not too many people have been in touch about this so there may be a small audience for this. So weigh up in your mind whether the effort is worth it for you.
Hey thanks for the headsup @pjfanning! This is my first step into hacktober, so I was looking for a first issue. Is there anything else in the Pekko repos that you are maintaining that could be considered in a more beginner level?