Hi Stefan and PJ, been following the thread. Couple of thoughts:
1. If we go in the direction of a separate repo for the docs, we could use either git submodule to get the apache/hamilton code over to autogenerate the docs. On the other hand, not sure if sphinx support this, but I know for mkdocs it is also enough to just have the package pip installed in the venv and it autogenerates API references from there. 2. For the "content" folder (static html + other things), would it make sense to keep that in a separate branch (i.e. "_docs") on apache/hamilton, so that when you clone the source you don't need to download the html in case you don't need it? Best, Jernej ________________________________ From: PJ Fanning <[email protected]> Sent: 14 June 2025 15:21 To: [email protected] <[email protected]> Subject: Re: How to set up & use hamilton.apache.org If the website code can't be readily removed from apache/hamilton repo - then we can just leave it as is. We can set up .asf.yaml in the apache/hamilton repo to publish the website. I think the default is to have the website static content in the 'content' directory. Stefan - can you build the static content for the website and put it in the 'content' directory. I can then try to set up .asf.yaml to deploy it. On Sat, 14 Jun 2025 at 15:09, Stefan Krawczyk <[email protected]> wrote: > > I can see a separate hamilton-site repo that contains the landing page, but > what about documentation that relies on source code (which is what > hamilton.dagworks.io currently is)? We'd still need a process to generate > that and push it somewhere to be published? > > On Sat, Jun 14, 2025 at 2:43 AM PJ Fanning <[email protected]> wrote: > > > It would be my preference to separate out the website docs from > > https://github.com/apache/hamilton/ and put them in a separate > > https://github.com/apache/hamilton-site/ repo. > > It simplifies the release of Apache Hamilton if we don't need to worry > > about reviewers having to check the source headers and licensing of > > everything needed for the website build too. > > The simplest initial set up is to have apache/hamilton-site git repo > > set up so that a Hamilton team member can checkout the > > apache/hamilton-site git repo and run the build on their own machine. > > The HTML etc for the website gets generated to a directory like > > `content` or `publish`. The Hamilton team member can then commit the > > content or publish directory into git. We can configure the .asf.yaml > > file so that the website is redeployed based on git commits that > > include changes to the `content` or `publish` dir. > > We can look into trying to automate this later. It will need time to > > interact with ASF Infra team to be allowed to have automated jobs > > commit to the git repo. > > > > On Sat, 14 Jun 2025 at 07:24, Stefan Krawczyk <[email protected]> > > wrote: > > > > > > Okay just so I mentally I understand. > > > > > > 1. We can have documentation source live under /docs > > > 2. When a PR that changes docs is created/merged we can kick off a github > > > workflow that builds these docs > > > 3. Is it correct that we could then push this built HTML to this other > > > hamilton-site repo? Is that correct? > > > 4. Then using the `.asf.yaml` in the hamilton-site repo, we could use > > > the .asf.yaml > > > directives > > > < > > https://cwiki.apache.org/confluence/display/INFRA/git+-+.asf.yaml+features#Git.asf.yamlfeatures-WebsitedeploymentserviceforGitrepositories > > > > > > to then publish which would update hamilton.apache.org. > > > > > > Is that right? > > > > > > Cheers, > > > > > > Stefan > > > > > > > > > > > > > > > > > > On Mon, Jun 9, 2025 at 5:02 AM PJ Fanning <[email protected]> wrote: > > > > > > > Redirecting to dev mailing list. Private mailing list is for 2 things > > > > - discussing and voting on new committers and discussing security > > > > issues. Everything else is meant to be discussed in public. > > > > > > > > The main doc for web site publishing is: > > > > https://github.com/apache/infrastructure-asfyaml/blob/main/README.md > > > > > > > > We already have a DNS entry set up for hamilton.apache.org. > > > > > > > > Most ASF projects push the static content for their web site to a > > > > directory in a git repo. We can create an apache/hamilton-site repo > > > > for this. > > > > > > > > There are other approaches that might be feasible. One example is > > > > pekko.apache.org content - most of it is rsynced to > > > > nightlies.apache.org and we use .htaccess files deployed to > > > > pekko.apache.org to allow the nightlies.apache.org content to be > > > > accessed as if it was deployed directly to pekko.apache.org. This > > > > avoids having to git commit the generated content (only the markdown > > > > files from which the HTML is generated are in git). > > > > > > > > > > > > On Mon, 9 Jun 2025 at 04:57, Stefan Krawczyk <[email protected]> > > > > wrote: > > > > > > > > > > Hi Mentors, > > > > > > > > > > I assume hamilton.apache.org is the front page for the project? > > > > > > > > > > I think it would currently make sense for the current docs page to be > > > > under that domain. > > > > > > > > > > So to enable that, what do we need to do? > > > > > > > > > > 1. The current docs are hosted on readthedocs.org -- can we > > continue to > > > > use that? or? > > > > > 2. If so, then we can add a new domain - hamilton.apache.org which > > > > would require a CNAME target to be added .. > > > > > 3. If not, the current docs are sphinx docs, how could we migrate > > them > > > > to the apache approved place? > > > > > > > > > > Cheers, > > > > > > > > > > Stefan > > > > > >
