Project Documentation Workflow

Project Documentation Workflow

[Peter Polidoro]

Hi,

I am looking for advice about the best way to create a 
documentation workflow for my projects. Maybe using Guix is the 
best way to solve this, maybe not.

I have a set of projects with a common theme, say each project is 
a circuit board that I have designed. Each project has its own git 
repository, containing the project files and channel.scm and 
guix.scm files to create reproducible development environments.

For each of these projects, I would like automatically generate 
project documentation. Some of the documentation information will 
be the same for all projects, some will be specific to each 
project.

For the information that is common to all projects, I want to be 
able to store that in a single location so each project can 
reference it and have access to the latest updates.

For information that is specific to each project, I want to store 
that inside each project directory.

I could solve this using Git tools, such as submodules or subtrees 
perhaps. I could have a repository that is the documentation 
skeleton and each project repository would have a reference to 
that skeleton repository. Then I would probably need to write some 
script to combine the local project files with the skeleton files 
to generate the specific project documentation.

I am wondering if a better approach might be to create a Guix 
package containing the documentation skeleton and each project 
inherits that package and applies local changes before generating 
the project documentation. I have not yet used Guix home, but 
perhaps that can be used for projects as well as home directories 
for such tasks?

Do any of you do anything similar and have any advice about the 
best way to organize such a set of project repositories with 
shared information? Thanks!

Re: Project Documentation Workflow

[Simon Tournier]

Hi,

On Fri, 01 Sep 2023 at 10:18, Peter Polidoro <peter@polidoro.io> wrote:

> I could solve this using Git tools, such as submodules or subtrees 
> perhaps. I could have a repository that is the documentation 
> skeleton and each project repository would have a reference to 
> that skeleton repository. Then I would probably need to write some 
> script to combine the local project files with the skeleton files 
> to generate the specific project documentation.

Well, from my understanding, you are describing a specific build system
for your documentation. :-)

> I am wondering if a better approach might be to create a Guix 
> package containing the documentation skeleton and each project 
> inherits that package and applies local changes before generating 
> the project documentation. I have not yet used Guix home, but 
> perhaps that can be used for projects as well as home directories 
> for such tasks?

Yeah, maybe having these documentation for each project as Guix
packages, you could share the common build system (script for building
the documentation) and inherit from one package to the other depending
on these projects.

Well, I have never needed to build many documentation. :-)


Cheers,
simon