Correct, the website is not built here.  `ant gen-doc` is just about the
code to adoc generated pages.

The asciidoc to webpage (antora build) is only done by cassandra-website.
We would like to be able to build a html/man bundle and ship it in
releases.  But that's not decided, and it wouldn't be part of `ant check`
or any other normal dev target.



On Mon, 28 Apr 2025 at 20:16, Patrick McFadin <pmcfa...@gmail.com> wrote:

> I don't think the website is generated outside of the Cassandra website
> repo. Did I miss that it's built when building the server?
>
> On Mon, Apr 28, 2025 at 10:19 AM Jon Haddad <j...@rustyrazorblade.com>
> wrote:
>
>> I strongly prefer we didn't install things on users systems they didn't
>> ask for.  I think we're also wasting people's time by building the website
>> by default.
>>
>> ant isn't a popular tool.  The more we ask people to know about it, the
>> more we turn people away from the project.  I'm personally unwilling to
>> invest the time in learning what's otherwise a dead technology, and I can't
>> be the only one.  We should by default do the thing that most people want
>> by default, which is building the server.
>>
>> Jon
>>
>> On Mon, Apr 28, 2025 at 9:54 AM Alex Petrov <al...@coffeenco.de> wrote:
>>
>>> I’ve talked to some folks privately and looks like ant jar is a more
>>> common workflow than just ant. I also don’t mind disabling check style and
>>> doc gen for my purposes. But I would suggest to not auto install, or hide
>>> installation behind a flag and suggest user to opt in to this.
>>>
>>> One more reason to not install is that this way we commit to maintaining
>>> installing go.
>>>
>>> Ideally we would not pull in one more language for a small task but it’s
>>> hard for me to judge how difficult it would’ve been to implement this
>>> feature differently.
>>>
>>> On Sun, Apr 27, 2025, at 6:20 PM, Mick Semb Wever wrote:
>>>
>>> Pulling out to a separate thread, as requested.
>>>
>>> Should golang auto-install when it's not found, when executing `ant
>>> gen-doc` ?
>>>
>>> Our build system has a number of path dependencies: e.g. ant, maven,
>>> python, golang, gradle, git, grep, curl, docker, make.  Gradle and golang
>>> will auto-install if not found.
>>>
>>> Golang was recently introduced for CASSANDRA-19915, helping consolidate
>>> and improve the website documentation pages for our native protocol
>>> specification.  This was work that came over from the gocql community.
>>>
>>> https://cassandra.apache.org/doc/latest/cassandra/reference/native-protocol.html
>>>
>>> https://github.com/apache/cassandra-website/tree/trunk/cqlprotodoc
>>>
>>> Both python and golang are dependencies for in-tree docs generation
>>> (`ant gen-doc`).  Python is also used for tests.
>>>
>>> While python is expected to be found, golang like gradle will be
>>> downloaded and installed if it is not.  But unlike gradle, golang is only
>>> temporarily installed into your $TMPDIR and only used for the native
>>> protocol doc page generation.
>>>
>>> https://github.com/apache/cassandra/blob/trunk/doc/scripts/process-native-protocol-specs-in-docker.sh
>>>
>>>
>>> If you don't want to be executing gen-doc (note that `ant jar` doesn't
>>> already), you can just add `-Dant.gen-doc.skip=true` to your ant
>>> cmdline/config.  `ant check` does invoke it, because code changes can break
>>> doc generation.
>>>
>>> Is this a problem ? Why ?  What can/should be done ?
>>>
>>>
>>>
>>>
>>> On Fri, 25 Apr 2025 at 13:13, Alex Petrov <al...@coffeenco.de> wrote:
>>>
>>>
>>> Thank you for input.
>>>
>>> I will disable gen-doc in addition to checkstyle locally, but I would
>>> still suggest that in short-term we should at very least remove/disable the
>>> part that auto-installs go (or at least have a discussion or vote about it,
>>> in case folks believe auto-installing is a good idea), but ideally in the
>>> long term we can find a solution that does not require go.
>>>
>>> On Thu, Apr 24, 2025, at 12:39 PM, Štefan Miklošovič wrote:
>>>
>>> I don't see it necessary to port Gradle stuff to Ant. I have noticed
>>> zero problems with it after CEP-15 merge. Basically a non-event.
>>>
>>> It just looks strange that we have Ant + Maven poms / resolver wired
>>> into it + submodule on Gradle. I mean ... wow. There is nothing wrong per
>>> se but ... strange. One would expect that more into the future we go, the
>>> more coherent / consistent everything related to the build system will be,
>>> not the other way around. But I totally get that this is just how things
>>> are for now and there is nobody to blame really.
>>>
>>> On Thu, Apr 24, 2025 at 10:39 AM Benedict <bened...@apache.org> wrote:
>>>
>>>
>>> We should separate out any grade discussion. I’m happy to migrate accord
>>> to ant if that’s the project preference, but there’s continual discussion
>>> to begin modularising Cassandra (at least a little), and a proposal to use
>>> grade for the modules - which might be a happy medium for everyone’s
>>> competing priorities.
>>>
>>>
>>> On 24 Apr 2025, at 07:26, Mick Semb Wever <m...@apache.org> wrote:
>>>
>>> 
>>> Does this also apply to gradle, which now gets downloaded and installed,
>>> and is the most recent addition ?
>>>
>>> The python requirement from gen-doc has been around for over three years
>>> now.
>>>
>>> I agree with the rationale that `ant` should default to `ant check`,
>>> keeping newcomers in mind while being more just a final pre-commit action
>>> for seasoned devs where `ant jar` is the typical dev loop.  I'm sure this
>>> has been discussed in the past.
>>>
>>>
>>>
>>> On Thu, 24 Apr 2025 at 08:16, Alex Petrov <al...@coffeenco.de> wrote:
>>>
>>>
>>> I didn’t say we should disable checks. I thought this was a purpose of
>>> CI : to check everything: there’s likely more to break semantically
>>> anyways, also harder to detect and fix. I’m also not proposing removing
>>> something that was long in place, these dependencies were introduced very
>>> recently.
>>>
>>> On Wed, Apr 23, 2025, at 11:51 PM, Jeremiah Jordan wrote:
>>>
>>> I think the default build should be to build and check everything.  I
>>> think that if someone is new it is better to have everything built and
>>> checked by default to flag issues.
>>>
>>> If someone knows what they are doing and wants to speed up the process
>>> it is very easy to add the right settings to the ant command so things are
>>> faster.
>>>
>>> -Jeremiah
>>>
>>> On Wed, Apr 23, 2025 at 4:36 PM Jordan West <jorda...@gmail.com> wrote:
>>>
>>> Should we consider making that the default and then passing false
>>> explicitly in CI/builds? I agree with Alex it’s a bit surprising and
>>> shorter build times when developing would be helpful.
>>>
>>> Jordan
>>>
>>> On Wed, Apr 23, 2025 at 13:37 Mick Semb Wever <m...@apache.org> wrote:
>>>
>>> Python and Go are used by the gen-doc target.
>>>
>>> Code changes can break these, hence it is part of `ant check`.
>>> It is not called by `ant jar`
>>>
>>> If you want to run check but skip it, it's to add
>>> `-Dant.gen-doc.skip=true`
>>>
>>>
>>>
>>> On Wed, 23 Apr 2025 at 22:06, Alex Petrov <al...@coffeenco.de> wrote:
>>>
>>>
>>> Hi folks,
>>>
>>> Building Cassandra jar has been getting increasingly slow, and now it
>>> looks like we depend not only on python3 (which was already not optimal),
>>> but also on go:
>>>
>>>     ant -Dno-checkstyle=true
>>>
>>> ...
>>>
>>>      [exec] python3 ./scripts/gen-nodetool-docs.py
>>>      [exec] python3 ./scripts/convert_yaml_to_adoc.py
>>> ../conf/cassandra.yaml
>>> ./modules/cassandra/pages/managing/configuration/cass_yaml_file.adoc
>>>      [exec] ./scripts/process-native-protocol-specs-in-docker.sh
>>>      [exec] Go env not found in your system, proceeding with
>>> installation.
>>>      [exec] Downloading Go 1.23.1...
>>>      [exec] Installing Go 1.23.1...
>>>      [exec] Building the cqlprotodoc...
>>>      [exec] Cloning into 'cassandra-website'...
>>>      [exec] Your branch is up to date with 'origin/trunk'.
>>>      [exec] go: downloading github.com/mvdan/xurls v1.1.0
>>>      [exec] Processing the .spec files...
>>>
>>> I personally consider this extremely dangerous, but also unnecessary. My
>>> current stance is that functionality introducing python3 and go should be
>>> moved to a separate task that only runs on demand / ci / release.  I
>>> welcome convincing arguments that would suggest otherwise.
>>>
>>> If you agree we should not require python and go to run `ant
>>> -Dno-checkstyle=true`, please also write a short message, this will be very
>>> helpful as well.
>>>
>>> Thank you,
>>> --Alex
>>>
>>>
>>>
>>>
>>>
>>>

Reply via email to