> On Dec 6, 2024, at 9:59 AM, Lari Hotari <lhot...@apache.org> wrote:
>
> Hi all,
>
> I'm starting a discussion about the website solution for the Hunter project.
>
> ASF provides multiple templates for different site frameworks at
> https://github.com/apache/apache-website-template.
I’ve had experience with pulsar-site (docusaurus), markdown, and asciidoc. I
did contract work for the ASF bringing ASF Pelican into use on apache/www-site,
etc. I did multiple migrations of OpenOffice.org within the ASF. I refreshed
the incubator.apache.org website which uses jBake/Groovy.
Pulsar is a large project which keeps every version of api docs in many
versions. The history and evolution to pulsar-site is long.
My opinion is that Hunter is a smaller project and docusaurus may be much more
than is needed.
The reality is that this is a choice between website templating systems and the
podling should choose a path that allows most of the community to be able to
maintain docs.
>
> In the Pulsar project, we use Docusaurus [1]. I would personally prefer using
> Docusaurus for Hunter as well, unless there are other preferences.
> At ASF, there is a solution that automatically publishes content from a
> branch to the website when the branch contains a `.asf.yaml` file with
> specific content matching the branch name (example [2], docs [3], source code
> comment [4]).
>
> The ASF template for Docusaurus is in the `docusaurus` branch of the
> apache-website-template repository at
> https://github.com/apache/apache-website-template/tree/docusaurus.
> One of the great features of Docusaurus is versioned documentation. Here's an
> example of Pulsar's documentation: https://pulsar.apache.org/docs/4.0.x/.
>
> Besides the site framework, we also need to decide whether we want to keep
> the website as part of the main repository in a folder or branch, or have it
> in an independent repository. I recommend creating a separate repository for
> the website so that we don't increase the size of the main repository with
> website-related revisions. I suggest creating a repository called
> "hunter-site" for the website.
Keeping these separate is a good idea unless documentation for hunter is to be
provided in a source release. If that is the case then a more nuanced choice
should be discussed.
>
> Do others have preferences for the website solution? What are your thoughts?
> What kind of content would we like to have on the website? Could we reuse
> some content that has been published about Hunter in the past and repurpose
> it for the website? How do we resolve copyright matters if content is reused?
These questions should be discussed before choosing the website framework.
Best,
Dave
>
> -Lari
>
> 1 - https://docusaurus.io/
> 2 - https://github.com/apache/pulsar-site/blob/asf-site-next/.asf.yaml
> 3 - https://infra.apache.org/asf-yaml.html
> 4 -
> https://github.com/apache/infrastructure-p6/blob/production/modules/gitbox/files/asfgit/package/asfyaml.py#L856-L863
