ibm / z_ansible_collections_doc Goto Github PK
View Code? Open in Web Editor NEWRepository for Z collections documentation
License: Apache License 2.0
Repository for Z collections documentation
License: Apache License 2.0
SUMMARY
Please generate new doc for ibm_zosmf collection using the dev branch where the latest RST resides.
NOTE:
There is no change to registry.yml , its still pointing to their dev branch so its simply just running the scripts to publish the updated doc.
ISSUE TYPE
Although not really a bug, its a warning but we try to keep these to minimum for those that we must accept, this appears to be one that could be corrected.
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zos_cics/CHANGELOG.rst: WARNING: document isn't included in any toctree
The CHANGELOG.rst if this is the same one required for certified content belongs in the root of your collections project.
As part of ibm_zos_core collection 1.4.1 release, the docs have been updated and we want to keep the release notes for 1.5.0-beta.1. I created the branch v1.4.1-docs. Kindly generate and update the docs for RHACC ibm_zos_core.
################################################################################
# Copyright (c) IBM Corporation 2020, 2021
################################################################################
################################################################################
# Configuration for Red Hat certified collections as part of the
# IBM Red Hat Certified Collection on Z offering
#
# For documentation to be generated and included in the offering pending the
# certfied registry process you must also include the required fields below.
#
# Instructions:
# <item>: The collection repository name as a dictionary element such as
# 'ibm_zos_core', 'ibm_zos_ims', etc
# git: The collection repository git url such as 'bm_zos_core.git'
# stable: The Git tag or branch name to generate stable documenation.
# latest: The Git tag or branch name to generate latest documenation.
#
# Notes:
# Only one version of documetation is currently generated and supported.
# Documentation is only generator for the latest branch or tag, there is plans
# to support both latest and stable in the near future.
################################################################################
collections:
ibm_zos_core:
git: [email protected]:ansible-collections/ibm_zos_core.git
stable:
latest: v1.4.1-docs
origin: main
ibm_zos_ims:
git: [email protected]:ansible-collections/ibm_zos_ims.git
stable:
latest: main
origin: main
ibm_zos_cics:
git: [email protected]:ansible-collections/ibm_zos_cics.git
stable:
latest: main
origin: main
zhmc-ansible-modules:
git: [email protected]:zhmcclient/zhmc-ansible-modules.git
stable:
latest: 1.0.2
origin: master
ibm_zos_sysauto:
git: [email protected]:ansible-collections/ibm_zos_sysauto.git
stable:
latest: v1.0.1
origin: main
ibm_zosmf:
git: [email protected]:IBM/ibm_zosmf.git
stable:
latest: dev
origin: main
SUMMARY
Please generate new doc for ibm_zosmf collection using the main
branch where the latest RST resides.
ISSUE TYPE
Hi - I have a customer using python, ZOAU and Ansible on z/OS. They have commented that it is becoming increasingly difficult to make sure that the three products are all at the right version for each other. They have said that it is ZOAU and the Ansible collections that seem to be causing the most grief. (One team looks after ZOAU and another Ansible). They wondered of the documentation for the pre-requisites of each could be made better/clearer?
The collection dependency requirements are not clear in the documentation (https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/requirements_managed.html).
Customers would like to know what versions of python and ZOAU they should install in order to run a certain version of Ansible (or specifically, the z/OS core collection).
For more information, see the slack thread:
https://ibm-systems-z.slack.com/archives/CGRPT7DRP/p1705338495015539
Update IBM z/OS Core collection doc for releae 1.9.0-beta.1
Tag is 1.9.0-beta.1 but the source is also in main
Ansible Galaxy is now Galaxy NG, all the previous link should be updated to this one:
https://galaxy.ansible.com/ui/search/?keywords=ibm_zos*
CICS has an update to fix a broken link, can @jennyhuang17 run the build and publish the new doc?
As part of ibm_zos_core collection v1.8.0-beta.1 release, the docs have been updated, latest is on main branch.
Currently, the support information in the doc site directs users to open a git issue. However, this should really be their last choice since they'll be unable to send their logs and this approach has no SLAs.
Recommended process for getting support should be similar to this:
Users can get support from either Red Hat or the community.
They should go to Red Hat first, if RH defines that the issue is related to IBM, it'll redirect users to IBM.
If users choose to get the community support, they should be aware that their issues might not be resolved right away.
Reference: https://ibm-systems-z.slack.com/archives/D02HN8Q7X5J/p1701219160689749
When running the makefile without the playbook wrapper you can get additional verbosity, i don't know why the playbook consumes it, anyhow zHMC docs error when running
make clean;make module-doc;make html;make view-html;
This error:
writing output... [100%] zhmc-ansible-modules/docs/source/requirements_managed
/Users/ddimatos/git/github/z_ansible_collections_doc/source/zhmc-ansible-modules/docs/source/development.rst:44: WARNING: undefined label: supported environments
While I did not try to fix it for good reason:
ref
is not visible without reviewing the RST docs closer, its possible the path is missingThe following versions of Ansible are supported:
- Ansible 2.9
- Ansible 2.10
- Ansible 3.0 (ansible-base 2.10)
- Ansible 4.0 (ansible-core 2.11)
- Ansible 5.0 (ansible-core 2.12)
Please generate new doc for ibm_zosmf collection using the dev
branch where the latest RST resides.
NOTE:
There is no change to registry.yml , its still pointing to their dev
branch so its simply just running the scripts to publish the updated doc.
As part of ibm_zos_core collection v1.7.0-beta.2 release, the docs have been updated, latest is on main branch.
################################################################################
# Copyright (c) IBM Corporation 2020, 2021
################################################################################
################################################################################
# Configuration for Red Hat certified collections as part of the
# IBM Red Hat Certified Collection on Z offering
#
# For documentation to be generated and included in the offering pending the
# certfied registry process you must also include the required fields below.
#
# Instructions:
# <item>: The collection repository name as a dictionary element such as
# 'ibm_zos_core', 'ibm_zos_ims', etc
# git: The collection repository git url such as 'bm_zos_core.git'
# stable: The Git tag or branch name to generate stable documenation.
# latest: The Git tag or branch name to generate latest documenation.
#
# Notes:
# Only one version of documetation is currently generated and supported.
# Documentation is only generator for the latest branch or tag, there is plans
# to support both latest and stable in the near future.
################################################################################
collections:
ibm_zos_core:
git: [email protected]:ansible-collections/ibm_zos_core.git
stable:
latest: main
origin: main
ibm_zos_ims:
git: [email protected]:ansible-collections/ibm_zos_ims.git
stable:
latest: main
origin: main
ibm_zos_cics:
git: [email protected]:ansible-collections/ibm_zos_cics.git
stable:
latest: main
origin: main
zhmc-ansible-modules:
git: [email protected]:zhmcclient/zhmc-ansible-modules.git
stable:
latest: 1.4.1
origin: master
ibm_zos_sysauto:
git: [email protected]:ansible-collections/ibm_zos_sysauto.git
stable:
latest: v1.0.1
origin: main
ibm_zosmf:
git: [email protected]:IBM/ibm_zosmf.git
stable:
latest: dev
origin: main
Update the docs to show the latest release docs
No need to update registry
Releasing new collection version 1.6.0-beta.1
to Galaxy.
Likely no update required, HEAD of main now contains v1.6.0-beta.1
changes
################################################################################
# Copyright (c) IBM Corporation 2020, 2021
################################################################################
################################################################################
# Configuration for Red Hat certified collections as part of the
# IBM Red Hat Certified Collection on Z offering
#
# For documentation to be generated and included in the offering pending the
# certfied registry process you must also include the required fields below.
#
# Instructions:
# <item>: The collection repository name as a dictionary element such as
# 'ibm_zos_core', 'ibm_zos_ims', etc
# git: The collection repository git url such as 'bm_zos_core.git'
# stable: The Git tag or branch name to generate stable documenation.
# latest: The Git tag or branch name to generate latest documenation.
#
# Notes:
# Only one version of documetation is currently generated and supported.
# Documentation is only generator for the latest branch or tag, there is plans
# to support both latest and stable in the near future.
################################################################################
collections:
ibm_zos_core:
git: [email protected]:ansible-collections/ibm_zos_core.git
stable:
latest: main
origin: main
ibm_zos_ims:
git: [email protected]:ansible-collections/ibm_zos_ims.git
stable:
latest: main
origin: main
ibm_zos_cics:
git: [email protected]:ansible-collections/ibm_zos_cics.git
stable:
latest: main
origin: main
zhmc-ansible-modules:
git: [email protected]:zhmcclient/zhmc-ansible-modules.git
stable:
latest: 1.0.2
origin: master
ibm_zos_sysauto:
git: [email protected]:ansible-collections/ibm_zos_sysauto.git
stable:
latest: v1.0.1
origin: main
ibm_zosmf:
git: [email protected]:IBM/ibm_zosmf.git
stable:
latest: dev
origin: main
Originally when the setup.sh was written it was based on the fact that MacOS at that time only had Python 2.x installed and thus the script would checkout python source, compile, build and install it as a required dependency that is no longer the case as MacOS includes later versions of python.
There are also some frozen package conflicts needing updates and general clean up of configurations
We have a pretty large and what appears to be dated skip list, we should evaluate if it needs to be this large still. No reason to leave what is not needed in a config any longer than needed.
exclude_patterns = exclude_patterns = [
'ibm_zos_cics/docs/source/index.rst',
'ibm_zos_cics/docs/source/installation.rst',
'ibm_zos_cics/docs/source/playbooks.rst',
'ibm_zos_cics/docs/source/requirements.rst',
'ibm_zos_cics/docs/zos-collection-index.rst',
'ibm_zos_core/docs/files/role_sample/roles.rst',
'ibm_zos_core/docs/source/index.rst',
'ibm_zos_core/docs/source/installation.rst',
'ibm_zos_core/docs/source/license.rst',
'ibm_zos_core/docs/source/playbooks.rst',
'ibm_zos_core/docs/source/requirements-single.rst',
'ibm_zos_core/docs/source/requirements.rst',
'ibm_zos_core/docs/zos-collection-index.rst',
'ibm_zos_ims/docs/source/index.rst',
'ibm_zos_ims/docs/source/installation.rst',
'ibm_zos_ims/docs/source/license.rst',
'ibm_zos_ims/docs/source/playbook_config_setup.rst',
'ibm_zos_ims/docs/source/playbook_group_vars.rst',
'ibm_zos_ims/docs/source/playbook_inventory.rst',
'ibm_zos_ims/docs/source/playbook_run.rst',
'ibm_zos_ims/docs/source/playbooks-single.rst',
'ibm_zos_ims/docs/source/playbooks.rst',
'ibm_zos_ims/docs/source/requirements-single.rst',
'ibm_zos_ims/docs/source/requirements.rst',
'ibm_zos_sysauto/docs/source/index.rst',
'ibm_zos_sysauto/docs/source/installation.rst',
'ibm_zos_sysauto/docs/source/license.rst',
'ibm_zos_sysauto/docs/source/playbooks.rst',
'ibm_zos_sysauto/docs/source/requirements.rst',
'ibm_zos_sysauto/docs/source/playbooks/sample_pb_create_dynres.rst',
'ibm_zos_sysauto/docs/source/playbooks/sample_pb_delete_dynres.rst',
'zhmc-ansible-modules/docs/source/community_guides.rst',
'zhmc-ansible-modules/docs/source/index.rst',
'zhmc-ansible-modules/docs/source/installation.rst',
'zhmc-ansible-modules/docs/source/playbooks.rst',
'zhmc-ansible-modules/docs/source/requirements.rst',
'zhmc-ansible-modules/docs/source/versioning.rst',
'howdoi/howdoi.rst',
'ibm_zosmf/docs/source/index.rst',
'ibm_zosmf/docs/source/requirements.rst',
'ibm_zosmf/docs/source/installation.rst',
'ibm_zosmf/docs/source/license.rst',
'ibm_zosmf/docs/source/playbooks.rst',
'ibm_zosmf/docs/source/requirements-single.rst'
]
IMS readme shows the text of core readme:
https://ibm.github.io/z_ansible_collections_doc/ibm_zos_ims/docs/ansible_content.html
Reference: https://docs.ansible.com/ansible/latest/porting_guides/porting_guide_8.html
We have a change log, a blog, discussion boards to announce changes but maybe users want more?
A customer request for reference: https://ibm-systems-z.slack.com/archives/D02HN8Q7X5J/p1701218686350609
The versions for Ansible and Python in Requirements needs update. See this blog for the latest versions.
When you run the playbook to generate doc, some errors are masked vs when you use the make file; for example:
ansible-playbook -i inventory site-builder.yml
vs make clean; make html; make view-html
When using make clean; make html; make view-html
you will see more detailed errors and till now, there have been 2 accepted known errors but the list has grown.
New errors that can likely be resolved:
reading sources... [100%] zhmc-ansible-modules/docs/source/requirements_managed
/Users/ddimatos/git/github/z_ansible_collections_doc/source/Troubleshooting/errorsandmessages.rst:63: WARNING: Unknown target name: "release notes".
/Users/ddimatos/git/github/z_ansible_collections_doc/source/Troubleshooting/errorsandmessages.rst:120: WARNING: Unknown target name: "installation doc".
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zos_core/docs/source/modules/zos_apf.rst:124: WARNING: Inline emphasis start-string without end-string.
/Users/ddimatos/git/github/z_ansible_collections_doc/source/index.rst:48: WARNING: toctree contains reference to nonexisting document 'troubleshooting/errorsandmessages'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/ddimatos/git/github/z_ansible_collections_doc/source/Troubleshooting/errorsandmessages.rst: WARNING: document isn't included in any toctree
This one from the above list is an accepted and known issue but the others above could be resolved.
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zos_core/docs/source/modules/zos_apf.rst:124: WARNING: Inline emphasis start-string without end-string.
One more new one further down in the tooling output that can be resolved.
writing output... [100%] zhmc-ansible-modules/docs/source/requirements_managed
/Users/ddimatos/git/github/z_ansible_collections_doc/source/zhmc-ansible-modules/docs/source/development.rst:44: WARNING: undefined label: supported environments (if the link has no caption the label must precede a section header)
generating indices... genindexdone
SUMMARY
Please generate new doc for ibm_zosmf collection using the dev branch where the latest RST resides.
NOTE:
There is no change to registry.yml , its still pointing to their dev branch so its simply just running the scripts to publish the updated doc.
ISSUE TYPE
Update Collection
While the playbooks are nice, they do have an issue in that they can eat the errors that Sphynx generates. I assume these have been here well over a year, probably closer to 2 yrs. Anyhow when running the make file to visually see the STDOUT, i noticed a number of errors: (venv) make clean;make module-doc;make html;make view-html;
updating environment: [new config] 114 added, 0 changed, 0 removed
reading sources... [100%] zhmc-ansible-modules/docs/source/requirements_managed
/Users/ddimatos/git/github/z_ansible_collections_doc/source/Troubleshooting/errorsandmessages.rst:63: ERROR: Unknown target name: "release notes".
/Users/ddimatos/git/github/z_ansible_collections_doc/source/Troubleshooting/errorsandmessages.rst:120: ERROR: Unknown target name: "installation doc".
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zos_core/docs/source/modules/zos_apf.rst:125: WARNING: Inline emphasis start-string without end-string.
/Users/ddimatos/git/github/z_ansible_collections_doc/source/index.rst:48: WARNING: toctree contains reference to nonexisting document 'troubleshooting/errorsandmessages'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/ddimatos/git/github/z_ansible_collections_doc/source/Troubleshooting/errorsandmessages.rst: WARNING: document isn't included in any toctree
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zos_core/CHANGELOG.rst: WARNING: document isn't included in any toctree
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zos_ims/CHANGELOG.rst: WARNING: document isn't included in any toctree
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zos_sysauto/CHANGELOG.rst: WARNING: document isn't included in any toctree
/Users/ddimatos/git/github/z_ansible_collections_doc/source/ibm_zosmf/CHANGELOG.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] zhmc-ansible-modules/docs/source/requirements_managed
/Users/ddimatos/git/github/z_ansible_collections_doc/source/zhmc-ansible-modules/docs/source/development.rst:44: WARNING: undefined label: supported environments
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 10 warnings.
The HTML pages are in build/html.
====================================================================
Completed HTML generation, see /Users/ddimatos/git/github/z_ansible_collections_doc/build/html; next run 'make view-html'
====================================================================
Display generated HTML 'build/html/index.html' in default browser.
(venv) git status
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
modified: .gitmodules
new file: source/ibm_zos_cics
new file: source/ibm_zos_core
new file: source/ibm_zos_ims
new file: source/ibm_zos_sysauto
new file: source/ibm_zosmf
new file: source/zhmc-ansible-modules
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: inventory
modified: source/ibm_zos_core (new commits)
modified: source/ibm_zos_ims (new commits)
modified: source/ibm_zos_sysauto (new commits)
modified: source/ibm_zosmf (new commits)
modified: source/zhmc-ansible-modules (new commits)
Untracked files:
(use "git add <file>..." to include in what will be committed)
build/
Please update the unified docs to reflect the latest v1.10.0 release changes.
We're releasing version 1.5.0 of the ibm_zos_core collection to Automation Hub and Galaxy, so I'd like to request for the docs to be updated on the doc site.
################################################################################
# Copyright (c) IBM Corporation 2020, 2021
################################################################################
################################################################################
# Configuration for Red Hat certified collections as part of the
# IBM Red Hat Certified Collection on Z offering
#
# For documentation to be generated and included in the offering pending the
# certfied registry process you must also include the required fields below.
#
# Instructions:
# <item>: The collection repository name as a dictionary element such as
# 'ibm_zos_core', 'ibm_zos_ims', etc
# git: The collection repository git url such as 'bm_zos_core.git'
# stable: The Git tag or branch name to generate stable documenation.
# latest: The Git tag or branch name to generate latest documenation.
#
# Notes:
# Only one version of documetation is currently generated and supported.
# Documentation is only generator for the latest branch or tag, there is plans
# to support both latest and stable in the near future.
################################################################################
collections:
ibm_zos_core:
git: [email protected]:ansible-collections/ibm_zos_core.git
stable:
latest: main
origin: main
ibm_zos_ims:
git: [email protected]:ansible-collections/ibm_zos_ims.git
stable:
latest: main
origin: main
ibm_zos_cics:
git: [email protected]:ansible-collections/ibm_zos_cics.git
stable:
latest: main
origin: main
zhmc-ansible-modules:
git: [email protected]:zhmcclient/zhmc-ansible-modules.git
stable:
latest: 1.0.2
origin: master
ibm_zos_sysauto:
git: [email protected]:ansible-collections/ibm_zos_sysauto.git
stable:
latest: v1.0.1
origin: main
ibm_zosmf:
git: [email protected]:IBM/ibm_zosmf.git
stable:
latest: dev
origin: main
We're releasing version 1.5.0 of the ibm_zos_core collection to Automation Hub and Galaxy, so I'd like to request for the docs to be updated on the doc site.
################################################################################
# Copyright (c) IBM Corporation 2020, 2021
################################################################################
################################################################################
# Configuration for Red Hat certified collections as part of the
# IBM Red Hat Certified Collection on Z offering
#
# For documentation to be generated and included in the offering pending the
# certfied registry process you must also include the required fields below.
#
# Instructions:
# <item>: The collection repository name as a dictionary element such as
# 'ibm_zos_core', 'ibm_zos_ims', etc
# git: The collection repository git url such as 'bm_zos_core.git'
# stable: The Git tag or branch name to generate stable documenation.
# latest: The Git tag or branch name to generate latest documenation.
#
# Notes:
# Only one version of documetation is currently generated and supported.
# Documentation is only generator for the latest branch or tag, there is plans
# to support both latest and stable in the near future.
################################################################################
collections:
ibm_zos_core:
git: [email protected]:ansible-collections/ibm_zos_core.git
stable:
latest: main
origin: main
ibm_zos_ims:
git: [email protected]:ansible-collections/ibm_zos_ims.git
stable:
latest: main
origin: main
ibm_zos_cics:
git: [email protected]:ansible-collections/ibm_zos_cics.git
stable:
latest: main
origin: main
zhmc-ansible-modules:
git: [email protected]:zhmcclient/zhmc-ansible-modules.git
stable:
latest: 1.0.2
origin: master
ibm_zos_sysauto:
git: [email protected]:ansible-collections/ibm_zos_sysauto.git
stable:
latest: v1.0.1
origin: main
ibm_zosmf:
git: [email protected]:IBM/ibm_zosmf.git
stable:
latest: dev
origin: main
Need to generate documentation for IMS Collection release v1.3.0-beta.1
Conref = cross reference, for documentation, a conref list is mostly used for trademarks, product names, version numbers, etc. The purpose of having a conref list for documentation is for better maintaining terms that could change often but occur many times in the documentation.
We should have something similar to this for the whole documentation.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.