1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
#!/usr/bin/env python
# --------------------------------------------------------------------------------------------
# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License. See License.txt in the project root for license information.
# --------------------------------------------------------------------------------------------
# This script is intended to be executed from within a tox script. It takes care of of unzipping
# an package sdist and prepping for a sphinx execution.
from m2r import parse_from_file
import glob
import logging
import shutil
import argparse
from pkg_resources import Requirement
import ast
import os
import textwrap
import io
from tox_helper_tasks import (
unzip_sdist_to_directory,
move_and_rename
)
from ci_tools.parsing import ParsedSetup
logging.getLogger().setLevel(logging.INFO)
RST_EXTENSION_FOR_INDEX = """
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. toctree::
:maxdepth: 5
:glob:
:caption: Developer Documentation
{}
"""
root_dir = os.path.abspath(os.path.join(os.path.abspath(__file__), "..", "..", ".."))
sphinx_conf = os.path.join(root_dir, "doc", "sphinx", "individual_build_conf.py")
def should_build_docs(package_name):
return not ("nspkg" in package_name or package_name in ["azure", "azure-mgmt", "azure-keyvault", "azure-documentdb", "azure-mgmt-documentdb", "azure-servicemanagement-legacy"])
def create_index_file(readme_location, package_rst):
readme_ext = os.path.splitext(readme_location)[1]
if readme_ext == ".md":
output = parse_from_file(readme_location)
elif readme_ext == ".rst":
with open(readme_location, "r") as file:
output = file.read()
else:
logging.error(
"{} is not a valid readme type. Expecting RST or MD.".format(
readme_location
)
)
output += RST_EXTENSION_FOR_INDEX.format(package_rst)
return output
def copy_conf(doc_folder):
if not os.path.exists(doc_folder):
os.mkdir(doc_folder)
shutil.copy(sphinx_conf, os.path.join(doc_folder, 'conf.py'))
def create_index(doc_folder, source_location, namespace):
index_content = ""
package_rst = "{}.rst".format(namespace)
content_destination = os.path.join(doc_folder, "index.rst")
if not os.path.exists(doc_folder):
os.mkdir(doc_folder)
# grep all content
markdown_readmes = glob.glob(os.path.join(source_location, "README.md"))
rst_readmes = glob.glob(os.path.join(source_location, "README.rst"))
# if markdown, take that, otherwise rst
if markdown_readmes:
index_content = create_index_file(markdown_readmes[0], package_rst)
elif rst_readmes:
index_content = create_index_file(rst_readmes[0], package_rst)
else:
logging.warning("No readmes detected for this namespace {}".format(namespace))
index_content = RST_EXTENSION_FOR_INDEX.format(package_rst)
# write index
with open(content_destination, "w+", encoding='utf-8') as f:
f.write(index_content)
def write_version(site_folder, version):
if not os.path.isdir(site_folder):
os.mkdir(site_folder)
with open(os.path.join(site_folder, "version.txt"), "w") as f:
f.write(version)
if __name__ == "__main__":
parser = argparse.ArgumentParser(
description="Prep a doc folder for consumption by sphinx."
)
parser.add_argument(
"-d",
"--dist_dir",
dest="dist_dir",
help="The dist location on disk. Usually /tox/dist.",
required=True,
)
parser.add_argument(
"-t",
"--target",
dest="target_package",
help="The target package directory on disk. The target module passed to pylint will be <target_package>/azure.",
required=True,
)
args = parser.parse_args()
package_path = os.path.abspath(args.target_package)
pkg_details = ParsedSetup.from_path(package_path)
if should_build_docs(pkg_details.name):
source_location = move_and_rename(unzip_sdist_to_directory(args.dist_dir))
doc_folder = os.path.join(source_location, "docgen")
create_index(doc_folder, source_location, pkg_details.namespace)
site_folder = os.path.join(args.dist_dir, "site")
write_version(site_folder, pkg_details.version)
else:
logging.info("Skipping sphinx prep for {}".format(pkg_details.name))
|
