During migration to the AsciiBinder framework in our project, I stumbled over a few conceptional issues especially when you having docs as part of the source code and you want to release docs along with the software itself and we treat docs the same as the code.
Explicit description of branches
If you want to build the docs, you have to describe the branch in the _distro_map.yml file. The repository lives inside a release branch. A quick out of my head suggestion to solve this issue would be, build and package the docs just for the current branch when no branches element exists in the _distro_map.yml and let someone pass a name and dir as an argument of the asciibinder command.
A scenario:
You hit the release button in your CI/CD system. We assume you have a branch which reflects a specific version number of the software and the documentation is part of this branch in the software repository. The CI/CD system does his job and the result is an installable artifact of the software and the documentation for this version is built and packaged and needs to be deployed to a public website. To use AsciiBinder in this scenario, it is required to mangle the _distro_map.yml to build the documentation just for this specific new version of the software.
Versioning docs
AsciiBinder requires having release branches. When a software is released, we use version tags and I haven't found a way to use the version tag as version number in AsciiBinder. Currently, in our case the version number is defined within Maven and is passed into the module which builds the documentation with the correct version number. I think this could be solved if it would be possible to pass version and deploy target parameters (what you define in the branches: element in the _distro_map.yml) to the asciibinder binary.
It seems to me I have to misuse AsciiBinder a lot to get it to work in this scenario and it is not built by design for such a use case.
Would be Interested about the opinion from maintainer about this scenario.
During migration to the AsciiBinder framework in our project, I stumbled over a few conceptional issues especially when you having docs as part of the source code and you want to release docs along with the software itself and we treat docs the same as the code.
Explicit description of branches
If you want to build the docs, you have to describe the branch in the
_distro_map.ymlfile. The repository lives inside a release branch. A quick out of my head suggestion to solve this issue would be, build and package the docs just for the current branch when nobrancheselement exists in the_distro_map.ymland let someone pass a name and dir as an argument of theasciibindercommand.A scenario:
You hit the release button in your CI/CD system. We assume you have a branch which reflects a specific version number of the software and the documentation is part of this branch in the software repository. The CI/CD system does his job and the result is an installable artifact of the software and the documentation for this version is built and packaged and needs to be deployed to a public website. To use AsciiBinder in this scenario, it is required to mangle the
_distro_map.ymlto build the documentation just for this specific new version of the software.Versioning docs
AsciiBinder requires having release branches. When a software is released, we use version tags and I haven't found a way to use the version tag as version number in AsciiBinder. Currently, in our case the version number is defined within Maven and is passed into the module which builds the documentation with the correct version number. I think this could be solved if it would be possible to pass version and deploy target parameters (what you define in the
branches:element in the_distro_map.yml) to theasciibinderbinary.It seems to me I have to misuse AsciiBinder a lot to get it to work in this scenario and it is not built by design for such a use case.
Would be Interested about the opinion from maintainer about this scenario.
Thank you in advance