Improve Doxygen

[Cayleb-Ordo]

In my personal Projects i have started to use this Doxygen style Theme: https://github.com/jothepro/doxygen-awesome-css .

I wanted to try it with the Pyrogenesis Doxygen, but i found that a vulkan header is always the Main Page of the doxygen. Is that wanted or could that be changed.

The header in question is source/third_party/vma/vk_mem_alloc.h.

I could not find any issues/requirements regarding the doxygen Policy.

 

[Gurken Khan]

@Freagarach?

[hyperion]

1 hour ago, Cayleb-Ordo said:

I wanted to try it with the Pyrogenesis Doxygen, but i found that a vulkan header is always the Main Page of the doxygen. Is that wanted or could that be changed.

It's not even our own code but 3rd party, so I'd call it a bug introduced with vma. A patch would be welcome I'd say.

About the stylesheet, I don't know, I like the purely functional touch of the original one but am not opposed to a different one either as long as its clean structure and information first.

About policy, well there is some mention in the CC on the wiki I believe but it's down for me so can't check. But basically the javadoc alike syntax is used in source code and if you submit patches people will yell anyway if you got it wrong

 

[Cayleb-Ordo]

Ok, i will try it without including the third_partys.

Regarding the Style, it only "updates" the visual of Doxygen, not the structure. Thats why i love it so much . 

[Stan`]

Currently there is not really a doxygen policy other than follow the style of the files you're touching.

Everything we generate is at docs.wildfiregames.com

[Cayleb-Ordo]

I have finished a first draft. It would be great if you could give me some feedback.  The links in the third_party Section point to their specific Github Page. I borrowed the logo from the website repository. Also, i dont know the current Version of the Engine, so i filled it with a placeholder.

[hyperion]

Just some random comments:

• About licenses, a link to the license file is missing.
• Version should just be the revision or in case it can't be fetched "latest" or "trunk" will do
• Todo list should be migrated to the bug tracker I think if there is really something left in there of value
• Maybe add a wrapper script build-docs.sh to the repo to generate the docs, for local use and in the Jenkinsfile
• The stylesheet looks fine at a glance

 

[Cayleb-Ordo]

 

42 minutes ago, hyperion said:

• Todo list should be migrated to the bug tracker I think if there is really something left in there of value

I think the Todo List is automatically generated by Doxygen if something is marked with "@todo".  It can be disabled in the doxygen config.

 

42 minutes ago, hyperion said:

 - Maybe add a wrapper script build-docs.sh to the repo to generate the docs, for local use and in the Jenkinsfile

I created a CMake File, that could also be used in a ci and locally. That limits the Version Numbering if used automatically to numbers. It could be set manually, if there is no "real" Version number. 

 

42 minutes ago, hyperion said:

• About licenses, a link to the license file is missing.

Ill try that.

 

Another thing i dont realy know is, how the SVN can handle git submodules. The doxygen-awesome-css could be bundled like other libs already are, but i think the submodule option is the cleanest.

Edited March 3 by Cayleb-Ordo

[hyperion]

33 minutes ago, Cayleb-Ordo said:

I think the Todo List is automatically generated by Doxygen if something is marked with "@todo".  It can be disabled in the doxygen config.

Yes, should be. The thing is that directive isn't really used. There are the classic // TODO and friends tho.

 

40 minutes ago, Cayleb-Ordo said:

I created a CMake File, that could also be used in a ci and locally. That limits the Version Numbering if used automatically to numbers. It could be set manually, if there is no "real" Version number. 

You can try to run svn info to get the revision. Using a shell script might be easier than using cmake. The value added by cmake for a doxy target is not much anyway.

 

44 minutes ago, Cayleb-Ordo said:

Another thing i dont realy know is, how the SVN can handle git submodules.

There is no "git submodule" support in svn at all, tho github has an svn interface I wouldn't go down that path. A supposed build-docs.sh could simply fetch a tarball, at least in a first installment of such a script.

[Cayleb-Ordo]

1 hour ago, hyperion said:

You can try to run svn info to get the revision. Using a shell script might be easier than using cmake. The value added by cmake for a doxy target is not much anyway.

I think it is more cross-platform and with the fetch_content we could get the doxygen-theme easily.

 

Edit: Indeed, it is very simple to integrate the theme using cmake fetch_content.

Edited March 3 by Cayleb-Ordo

[hyperion]

30 minutes ago, Cayleb-Ordo said:

I think it is more cross-platform and with the fetch_content we could get the doxygen-theme easily.

Then just make sure the cmake version available on the CI is recent enough or can be updated for your needs.

[Cayleb-Ordo]

is there a way to test the ci stuff? I saw the docker files and they are on debian buster, which is old old stable.

[hyperion]

5 hours ago, Cayleb-Ordo said:

is there a way to test the ci stuff? I saw the docker files and they are on debian buster, which is old old stable.

The "Dockerfile"s for the CI are in the repo, so in principle you have access. Repology suggest buster comes with cmake-3.13. There is backports for buster and the Dockerfile could be updated to fetch or even build a newer release, tho that would probably need some broader consensus as that would mean we indirectly bump the requirements.

[Cayleb-Ordo]

@hyperion Do you know which is the right contact person to talk about changing this?

[Stan`]

I don't think anyone is actively maintaining the CI now that I retired.

The point is that we usually update dependencies when we can no longer support the platform because say we updated spidermonkey and it requires C++17.

We have a custom image based on the other for doxygen here. https://trac.wildfiregames.com/browser/ps/trunk/build/jenkins/dockerfiles/gcc7-docs.Dockerfile

So in theory it wouldn't be too much breaking to only update that image to generate docs. We could also bundle whatever css is in there in the image dunno.

 

[Cayleb-Ordo]

Unterstood, then I will create a dockerfile only for the documentation. If i have time, i will test it with a self hosted jenkins server. 

 

Thought i give you the latest version of it.

Edited March 4 by Cayleb-Ordo

[Cayleb-Ordo]

So, i tried to understand where to put the new Dockerfile. I located the build Pipeline for the Dockers, but the docs-Docker is not build there. My current understanding of the Pipelines is that in order to add a new Docker Image, i have to add it to the build-docker Pipeline and modify the Docs Pipeline. But i did not get where i can tell the Pipeline which image should be used. It would be great if i could be corrected if i am wrong.

By the way, interesting way to use zfs pools. Never seen them used like this before.

[hyperion]

You'd replace

build/jenkins/dockerfiles/gcc7-docs.Dockerfile

Pipeline to rebuild docker images but missing this one (maybe manually created):

build/jenkins/pipelines/docker-reset.Jenkinsfile

Pipeline generating docs:

build/jenkins/pipelines/docker-docs.Jenkinsfile

 

The ones in svn and running on the CI might not be fully in sync, @Stan` would know

 

[Stan`]

Ah it would seem I never updated this file https://trac.wildfiregames.com/browser/ps/trunk/build/jenkins/pipelines/docker-reset.Jenkinsfile

 

/* Copyright (C) 2022 Wildfire Games.
 * This file is part of 0 A.D.
 *
 * 0 A.D. is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * 0 A.D. is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with 0 A.D.  If not, see <http://www.gnu.org/licenses/>.
 */

// This is a helper pipeline to build Docker images and setup ZFS volumes.

pipeline {
	agent {
		node {
			label 'LinuxSlave'
			customWorkspace '/zpool0/trunk'
		}
	}
	parameters {
		booleanParam(name: 'no-cache', defaultValue: false, description: 'Rebuild containers from scratch')
		booleanParam(name: 'reset-volumes', defaultValue: false, description: 'Reset ZFS volumes')
	}

	stages {
		stage("Cleanup") {
			steps {
				sh 'docker system prune -f'
			}
		}
		stage("Full Rebuild") {
			when {
				environment name: 'no-cache', value: 'true'
			}
			steps {
				sh 'docker build --no-cache -t build-base ~/dockerfiles/build-base'
				sh 'docker build --no-cache -t 0ad-gcc7 ~/dockerfiles/gcc7'
				sh 'docker build --no-cache -t 0ad-gcc7-docs ~/dockerfiles/gcc7-docs'
				sh 'docker build --no-cache -t 0ad-clang8 ~/dockerfiles/clang8'
				sh 'docker build --no-cache -t 0ad-translations ~/dockerfiles/translations'
			}
		}
		stage("Build") {
			when {
				environment name: 'no-cache', value: 'true'
			}
			steps {
				sh 'docker build -t build-base ~/dockerfiles/build-base'
				sh 'docker build -t 0ad-gcc7 ~/dockerfiles/gcc7'
				sh 'docker build -t 0ad-gcc7-docs ~/dockerfiles/gcc7-docs'
				sh 'docker build -t 0ad-clang8 ~/dockerfiles/clang8'
				sh 'docker build -t 0ad-translations ~/dockerfiles/translations'
				sh """
					docker rmi debian:buster
					DANGLING_IMAGES="\$(docker images --filter \"\"\"dangling=true\"\"\" -q --no-trunc)"
					if [ -n "\$DANGLING_IMAGES" ]; then
							echo "Removing dangling images: \$DANGLING_IMAGES"
							docker rmi \$(docker images --filter \"\"\"dangling=true\"\"\" -q --no-trunc)
							echo "Done."
					else
							echo "No dangling images found."
					fi
				"""
			}
		}
		stage("Update") {
			steps {
				sh "svn cleanup 2>/dev/null || true"
				svn "https://svn.wildfiregames.com/public/ps/trunk"
				sh "svn st --no-ignore | cut -c 9- | xargs rm -rf"
				sh "svn revert -R ."
			}
		}
		stage("Volumes") {
			when {
				environment name: 'reset-volumes', value: 'true'
			}
			steps {
				sh "sudo zfs destroy -R zpool0/trunk@base || true"
				sh "sudo zfs destroy -R zpool0/trunk@latest || true"

				sh "sudo zfs snapshot zpool0/trunk@base"
				sh "sudo zfs clone zpool0/trunk@base zpool0/gcc7"
				sh "sudo zfs clone zpool0/trunk@base zpool0/clang8"
				sh "sudo zfs snapshot zpool0/trunk@latest"
				sh "sudo zfs snapshot zpool0/clang8@latest"
				sh "sudo zfs snapshot zpool0/gcc7@latest"
			}
		}
	}
}

 

But basically you need to build base, then gcc7 then the docs one.

docker build -t build-base build-base.Dockerfile
docker build -t 0ad-gcc7 gcc7.Dockerfile
docker build -t 0ad-gcc7-docs gcc7-docs.Dockerfile

 

15 hours ago, Cayleb-Ordo said:

By the way, interesting way to use zfs pools. Never seen them used like this before.

Yeah @Itmsdid some nice engineering there. Basically disk space is sparse on the VM and and cloning is very long, so we saved a lot of time and space.

[Cayleb-Ordo]

@Stan` regarding the docs Pipeline, is it necessary to build pyrogenesis? Or could that be removed and only build doxygen and the entity docs?

[hyperion]

5 hours ago, Cayleb-Ordo said:

entity docs

That stage runs pyrogenesis which is only possible if pyrogenesis is built.

[Cayleb-Ordo]

Ok, then ill keep that. Only thing left now is to get the hang with Phabricator .