Building and deploying Doxygen documentation in Github pages.

[robertosfield]

I am currently looking at the possibility of getting Github to automatically build and host documentation, I haven't attempted this before and am no expert on Github Actions/Pages etc. so it's a case of learning what is required and then trying it out

My first place to start is to simple do a search online, these are two of hits I got, I don't know the latest greatest or simplest approach so I'll just read through this and glean what I can.

https://github.com/marketplace/actions/doxygen-action

https://gist.github.com/shundhammer/ed359db0d9329d4db551528256060d2a

What I'd like to end up with is a combination of markdown files and automatically generated doxygen files that can be browsed either locally when folks checkout the VSG and build their own local doxygen docs, or simply browsed online. Part of this will be getting the automated docs hosted here on Github and partly will be down to figuring out a reliable filename/URL mapping for doxygen files of different types so we can directly reference them from .md files and be confident that they'll be reliable links.

If there are members of the VSG community that have done this before then I'd appreciate any insights/help you can provide to short cut the process.

[robertosfield]

We already have some automated documentation support built in:

https://github.com/vsg-dev/VulkanSceneGraph/blob/master/.github/workflows/build-docs.yml

I can run this action and the report includes a link to zipped documentation file that can be download:

https://github.com/vsg-dev/VulkanSceneGraph/actions/runs/4185638076

However, what I am looking for is documentation that can remain hosted on a github server and browsed like a web page. It might be a very simple extra step and require a completely different workflow.

[ghost]

You could write API documentation in markdown, you can feed the header files (.h files) to ChatGPT, and use a prompt similar to this one.

Provide a table in markdown format that lists all of the class methods, and put the markdown 
code in code blocks? Finally, could you please give me a simple example that shows 
how to use the vsg::Allocator class?

Allocator Class (core)
The Allocator class provides methods for allocating and deallocating memory, as well as for reporting on the current state of memory usage. It also defines two enumerations, AllocatorType and AllocatorAffinity, that are used to configure the behavior of the allocator.

Method	Description
Allocator(std::unique_ptr<Allocator> in_nestedAllocator = {})	Constructor. Creates a new Allocator object with an optional nested allocator.
virtual ~Allocator()	Destructor.
static std::unique_ptr<Allocator>& instance()	Returns a singleton instance of the Allocator.
virtual void* allocate(std::size_t size, AllocatorAffinity allocatorAffinity = ALLOCATOR_AFFINITY_OBJECTS)	Allocates memory of a given size with the specified affinity.
virtual bool deallocate(void* ptr, std::size_t size)	Deallocates memory that was previously allocated with the allocate() method.
virtual size_t deleteEmptyMemoryBlocks()	Deletes any empty memory blocks.
virtual size_t totalAvailableSize() const	Returns the total amount of available memory in allocated memory blocks.
virtual size_t totalReservedSize() const	Returns the total amount of reserved memory in allocated memory blocks.
virtual size_t totalMemorySize() const	Returns the total amount of memory used by allocated memory blocks.
virtual void report(std::ostream& out) const	Reports statistics about the memory blocks managed by the Allocator.
void setMemoryTracking(int mt)	Sets the MemoryTracking member of the Allocator and all the memory blocks it manages.
MemoryBlocks* getMemoryBlocks(AllocatorAffinity allocatorAffinity)	Returns a pointer to the memory blocks with the specified affinity.
MemoryBlocks* getOrCreateMemoryBlocks(AllocatorAffinity allocatorAffinity, const std::string& name, size_t blockSize)	Returns a pointer to the memory blocks with the specified affinity, creating them if necessary.
void setBlockSize(AllocatorAffinity allocatorAffinity, size_t blockSize)	Sets the size of the memory blocks with the specified affinity.

Example

#include <vsg/core/Allocator.h>

int main()
{
    // Allocate memory using the Allocator
    void* mem = vsg::Allocator::instance()->allocate(1024);

    // Deallocate memory using the Allocator
    vsg::Allocator::instance()->deallocate(mem, 1024);

    return 0;
}

[robertosfield]

While impressively close to what we need, it misses the intent of vsg::Allocator and how it's actually intended to be used, i.e. it's used by the scene graph objects new/delete implementations to do block allocation of similar typed objects. It's more of internal implementation detail for performance reasons that a public class that users would use directly.

[ghost]

Out of curiosity I wanted to see what it could tell me . Is chatgpt's response accurate?

Prompt:

Is vsg::Allocator meant to be used by the end user or is it an internal class meant to be used by the engine.

Response:

vsg::Allocator is an internal class in VSG, and it is not meant to be used directly by end-users of 
the library. Instead, it is designed to be used by the engine as a low-level memory allocator that 
can allocate and manage memory for Vulkan resources such as buffers and images.

End-users of the VSG library are typically expected to use higher-level abstractions provided 
by the library, such as vsg::Buffer or vsg::Image, which internally use vsg::Allocator to allocate 
and manage memory. This allows end-users to focus on creating and manipulating graphics and 
compute resources without worrying too much about the underlying memory management details.

[Modenbach]

Hmmm... To be honest, at least OSG documentation is also not very verbose in this direction. Am 07.03.2023 um 12:34 schrieb Robert Osfield:

…

While impressively close to what we need, it misses the intent of vsg::Allocator and how it's actually intended to be used, i.e. it's used by the scene graph objects new/delete implementations to do block allocation of similar typed objects. It's more of internal implementation detail for performance reasons that a public class that users would use directly. — Reply to this email directly, view it on GitHub <#724 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A4NEOAZHDV6WKO6OSSCPASLW24MMZANCNFSM6AAAAAAU47BLPU>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>