Skip to content

Commit c6c5110

Browse files
stewartfrancisstewartfrancis
authored
Merge pull request #104 from ddimatos/ddimatos/v1.0.3_doc
Use core's Makefile to generate RST
2 parents 1bdf448 + 9b78441 commit c6c5110

File tree

6 files changed

+4899
-22
lines changed

6 files changed

+4899
-22
lines changed

‎docs/Makefile‎

Lines changed: 208 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,225 @@
1-
# (c) Copyright IBM Corp. 2020,2021
2-
# Minimal makefile for Sphinx documentation
3-
#
1+
##############################################################################
2+
# © Copyright IBM Corporation 2020 #
3+
##############################################################################
44

55
# You can set these variables from the command line, and also
66
# from the environment for the first two.
77
SPHINXOPTS ?=
88
SPHINXBUILD ?= sphinx-build
99
SOURCEDIR = source
1010
BUILDDIR = build
11+
ROOT_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
12+
OS_DISTRO := $(shell uname)
13+
INDEX_HTML = build/html/index.html
14+
line_header="===================================================================="
15+
16+
.PHONY: help Makefile
1117

1218
# Put it first so that "make" without argument is like "make help".
1319
help:
14-
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
20+
@echo $(line_header)
21+
@echo "Examples:"
22+
@echo "$(line_header)"
23+
@echo " make clean;make role-doc;make html;make view-html;"
24+
@echo " make clean;make module-doc;make html;make view-html;"
25+
@echo " make clean;make module-doc;make role-doc;make html;make view-html;"
26+
@echo " make clean;"
1527

16-
.PHONY: help Makefile
28+
@echo $(line_header)
29+
@echo "Make file targets"
30+
@echo "$(line_header)"
31+
@echo "clean - will remove unnecessary documentation and generated documentation artifacts:"
32+
@echo " - deletes $(ROOT_DIR)/build"
33+
@echo " - deletes $(ROOT_DIR)/source/modules"
34+
@echo " - deletes $(ROOT_DIR)/source/roles"
35+
@echo " - deletes ../plugins/modules/rexx_module_doc"
36+
@echo " - resets __init__.py.skip"
37+
@echo " - deletes $(ROOT_DIR)/build"
38+
@echo "role-doc - scans collection for roles; generate RST from role metadata."
39+
@echo "module-doc - scans collection for modules; generate RST for REXX and python modules."
40+
@echo "pre - <deprecated> Combines multiple RST int one, invokes external script."
41+
@echo "html - generates HTML to $(ROOT_DIR)/build/html."
42+
@echo "version-html - generates HTML with versions, requires necessary dependencies."
43+
@echo "view-html - displays generated HTML in your default browser."
1744

18-
# Catch-all target: route all unknown targets to Sphinx using the new
19-
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
20-
%: Makefile
21-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
22-
echo "Completed HTML text generation, run 'make view'"
45+
@echo $(line_header)
46+
@echo "Sphinx target type options"
47+
@echo $(line_header)
48+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
49+
50+
view-html:
51+
ifeq ($(shell test -e $(INDEX_HTML) && echo true),true)
52+
@echo "Display generated HTML '$(INDEX_HTML)' in default browser."
53+
ifeq ($(OS_DISTRO), Darwin)
54+
@open build/html/index.html
55+
else ifeq ($(OS_DISTRO), Linux)
56+
@xdg-open build/html/index.html &> /dev/null &
57+
else
58+
@echo "Unable to launch browser for $(INDEX_HTML), open file with your browser."
59+
endif
60+
else
61+
@echo "Unable to find generated HTML '$(INDEX_HTML)'."
62+
endif
2363

2464
clean:
25-
rm -rf build
26-
echo "Deleted directory build/"
65+
@echo $(line_header)
66+
@echo "Running Target clean"
67+
@echo $(line_header)
68+
69+
@if test -d build; then \
70+
echo "Deleting directory '$(ROOT_DIR)/build'."; \
71+
rm -rf build; \
72+
fi
73+
74+
@if test -d source/modules; then \
75+
echo "Deleting directory '$(ROOT_DIR)/source/modules'."; \
76+
rm -rf source/modules; \
77+
fi
78+
79+
@if test -d source/roles; then \
80+
echo "Deleting directory '$(ROOT_DIR)/source/roles'."; \
81+
rm -rf source/roles; \
82+
fi
83+
84+
@if test -d ../plugins/modules/rexx_module_doc; then \
85+
echo "Deleting directory '../plugins/modules/rexx_module_doc'."; \
86+
rm -rf ../plugins/modules/rexx_module_doc; \
87+
fi
88+
89+
@if test -e ../plugins/modules/__init__.py.skip; then \
90+
echo "Reset __init__.py.skip for '../plugins/modules/__init__.py'"; \
91+
mv -f ../plugins/modules/__init__.py.skip ../plugins/modules/__init__.py; \
92+
fi
93+
94+
@echo "Completed cleanup, run 'make module-doc' or 'make role-doc'."
95+
96+
role-doc:
97+
@echo $(line_header)
98+
@echo "Running Target role-doc"
99+
@echo $(line_header)
100+
101+
@if ! test -d build; then \
102+
mkdir build; \
103+
echo "Make $(ROOT_DIR)/build directory for Sphinx generated HTML."; \
104+
fi
105+
106+
@if ! test -d source/roles; then \
107+
mkdir -p source/roles; \
108+
echo "Make $(ROOT_DIR)/source/roles directory for Sphinx generated HTML."; \
109+
fi
110+
111+
@for role_name in `ls ../roles/`; do \
112+
echo "Detected role name $$role_name"; \
113+
if test -e ../roles/$$role_name/docs/doc_$$role_name; then \
114+
echo "Copying metadata ../roles/$$role_name/docs/doc_$$role_name to ../roles/$$role_name/docs/doc_$$role_name.py"; \
115+
cp ../roles/$$role_name/docs/doc_$$role_name ../roles/$$role_name/docs/doc_$$role_name.py; \
116+
echo "Sanitizing metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
117+
sed -i -e "s/^role:/module:/" ../roles/$$role_name/docs/doc_$$role_name.py; \
118+
echo "Generating RST doc for role ../roles/$$role_name"; \
119+
ansible-doc-extractor --template templates/role.rst.j2 source/roles ../roles/$$role_name/docs/doc_$$role_name.py; \
120+
echo "Deleting generated metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
121+
rm -rf ../roles/$$role_name/docs/doc_$$role_name.py; \
122+
fi; \
123+
done
124+
125+
@echo $(line_header)
126+
@echo "Completed ReStructuredText generation for roles; next run 'make html'"
127+
@echo $(line_header)
128+
129+
module-doc:
130+
@echo $(line_header)
131+
@echo "Running Target module-doc"
132+
@echo $(line_header)
27133

28-
rm -rf source/modules
29-
echo "Deleted directory source/modules"
134+
@if ! test -d build; then \
135+
echo "Make $(ROOT_DIR)/build directory for Sphinx generated HTML."; \
136+
mkdir build; \
137+
fi
138+
139+
@if ! test -d source/modules; then \
140+
echo "Make $(ROOT_DIR)/source/modules directory for Sphinx generated HTML."; \
141+
mkdir -p source/modules; \
142+
fi
143+
144+
# @if ! test -d ../plugins/modules/rexx_module_doc; then \
145+
# echo "Make ../plugins/modules/rexx_module_doc directory to extract REXX doc into temporary file."; \
146+
# mkdir -p ../plugins/modules/rexx_module_doc; \
147+
# else \
148+
# echo "Delete ../plugins/modules/rexx_module_doc directory used to extract REXX doc into temporary file."; \
149+
# rm -rf ../plugins/modules/rexx_module_doc; \
150+
# echo "Make ../plugins/modules/rexx_module_doc directory to extract REXX doc into temporary file."; \
151+
# mkdir -p ../plugins/modules/rexx_module_doc; \
152+
# fi
153+
154+
# @for rexx_module in `ls ../plugins/modules/*rexx`; do\
155+
# REXX_FILE=`basename $$rexx_module .rexx`; \
156+
# echo "Extracting documentation for module $$REXX_FILE into ../plugins/modules/rexx_module_doc/$$REXX_FILE.py"; \
157+
# touch ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
158+
# sed -n "/DOCUMENTATION = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
159+
# sed -n "/EXAMPLES = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
160+
# sed -n "/RETURN = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
161+
# echo "Generating ReStructuredText for module $$REXX_FILE inot source/modules/$$REXX_FILE.rst"; \
162+
# ansible-doc-extractor --template templates/module.rst.j2 source/modules ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
163+
# done
164+
165+
# @if test -d ../plugins/modules/rexx_module_doc; then \
166+
# echo "Delete ../plugins/modules/rexx_module_doc directory used to extract REXX doc into temporary file."; \
167+
# rm -rf ../plugins/modules/rexx_module_doc; \
168+
# fi
169+
170+
@if test -e ../plugins/modules/__init__.py; then \
171+
echo "Rename file '../plugins/modules/__init__.py' to ../plugins/modules/__init__.py.skip to avoid reading empty python file.'"; \
172+
mv ../plugins/modules/__init__.py ../plugins/modules/__init__.py.skip; \
173+
fi
174+
175+
@echo "Generating ReStructuredText for all ansible modules found at '../plugins/modules/' to 'source/modules'."
176+
@ansible-doc-extractor --template templates/module.rst.j2 source/modules ../plugins/modules/*.py
177+
178+
@if test -e ../plugins/modules/__init__.py.skip; \
179+
echo "Rename file '../plugins/modules/__init__.py.skip' back to ../plugins/modules/__init__.py.'"; \
180+
then mv -f ../plugins/modules/__init__.py.skip ../plugins/modules/__init__.py; \
181+
fi
182+
183+
@echo $(line_header)
184+
@echo "Completed ReStructuredText generation for modules; next run 'make html'"
185+
@echo $(line_header)
186+
187+
pre:
188+
@echo $(line_header)
189+
@echo "Running Target pre"
190+
@echo $(line_header)
191+
192+
@$(shell scripts/auto-doc-gen.sh)
193+
194+
@echo $(line_header)
195+
@echo "Completed auto-doc-generation see script auto-doc-gen.sh for details"
196+
@echo $(line_header)
30197

31198
html:
32-
mkdir build
33-
mkdir -p source/modules
34-
echo "Extract docs from modules"
35-
python ansible-doc-extractor-collections.py
36-
@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
37-
38-
view:
39-
open build/html/index.html
199+
@echo $(line_header)
200+
@echo "Running Target html"
201+
@echo $(line_header)
202+
203+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
204+
205+
@echo $(line_header)
206+
@echo "Completed HTML generation, see $(ROOT_DIR)/build/html; next run 'make view-html' "
207+
@echo $(line_header)
208+
209+
version-html:
210+
@echo $(line_header)
211+
@echo "Running Target version-html"
212+
@echo $(line_header)
213+
214+
# @sphinx-versioning -l "$(ROOT_DIR)"/source/conf.py build "$(ROOT_DIR)"/source/ "$(ROOT_DIR)"/build/html -- -D html_show_sphinx=False
215+
@sphinx-versioning -l "$(ROOT_DIR)"/source/conf.py build "$(ROOT_DIR)"/source/ "$(ROOT_DIR)"/build/html
216+
217+
@echo $(line_header)
218+
@echo "Completed HTML generation for GitHub repository branches and/or tags, next run 'make view-html'"
219+
@echo $(line_header)
220+
221+
# Catch-all target: route all unknown targets to Sphinx using the new
222+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
223+
%: Makefile
224+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
225+
@echo "Completed HTML text generation, run 'make view-html'"

0 commit comments

Comments
 (0)