def test_storage_sphinx_image_candidate(self):
config = prepare_conf()
assets_dir = os.path.join(self.test_dir, 'assets')
sample_img = os.path.join(assets_dir, 'test.png')
for mime_type in SUPPORTED_IMAGE_TYPES:
ext = mimetypes.guess_extension(mime_type)
# handle python 3.7 interpreter | image/x-ms-bmp -> image/bmp
# https://bugs.python.org/issue22589
if not ext and mime_type == 'image/x-ms-bmp':
ext = mimetypes.guess_extension('image/bmp')
self.assertIsNotNone(ext)
pyver = 'py{}{}'.format(sys.version_info.major,
sys.version_info.minor)
doc_dir = prepare_dirs(
postfix='-{}-docs-{}'.format(pyver, ext[1:]))
out_dir = prepare_dirs(postfix='-{}-out-{}'.format(pyver, ext[1:]))
# prepare documentation set
# - create and index document with an asterisk image extension
# - copies over an image which should be mapped; note that a real
# image is needed as the contents can be parsed through sphinx
# to see if its a real image before considering it to be a
# candidate
os.makedirs(doc_dir)
index_file = os.path.join(doc_dir, 'index.rst')
with open(index_file, 'w') as f:
f.write('.. image:: candidate.*')
img_filename = 'candidate' + ext
dummy_img_file = os.path.join(doc_dir, img_filename)
shutil.copyfile(sample_img, dummy_img_file)
# build and check
build_sphinx(doc_dir, config=config, out_dir=out_dir)
with parse('index', out_dir) as data:
image = data.find('ac:image')
self.assertIsNotNone(image)
attachment = image.find('ri:attachment', recursive=False)
self.assertIsNotNone(attachment)
self.assertTrue(attachment.has_attr('ri:filename'))
self.assertEqual(attachment['ri:filename'], img_filename)
def test_extensions(self):
config = self.config.clone()
config['confluence_sourcelink']['container'] += 'extensions/'
config['extensions'].append('sphinx.ext.autodoc')
config['extensions'].append('sphinx.ext.autosummary')
config['extensions'].append('sphinx.ext.graphviz')
config['extensions'].append('sphinx.ext.ifconfig')
config['extensions'].append('sphinx.ext.inheritance_diagram')
config['extensions'].append('sphinx.ext.todo')
config['graphviz_output_format'] = 'svg'
config['todo_include_todos'] = True
config['todo_link_only'] = True
# inject a navdoc from the last header/footer page, to the
# extended autodocs start page
def navdocs_transform(builder, docnames):
builder.state.register_title('_validation_prev', 'Markdown Table',
None)
docnames.insert(0, '_validation_prev')
builder.state.register_title('_validation_next',
'Extended - autodocs', None)
docnames.append('_validation_next')
return docnames
config['confluence_navdocs_transform'] = navdocs_transform
dataset = os.path.join(self.datasets, 'extensions')
doc_dir = prepare_dirs('validation-set-extensions')
sys.path.insert(0, os.path.join(dataset, 'src'))
build_sphinx(dataset, config=config, out_dir=doc_dir)
sys.path.pop(0)
def test_extended_autodocs(self):
if parse_version(sphinx_version) < parse_version('2.3.1'):
raise unittest.SkipTest('breathe requires sphinx>=2.3.1')
config = self.config.clone()
config['confluence_sourcelink']['container'] += 'extended-autodocs/'
config['extensions'].append('breathe')
config['extensions'].append('sphinx.ext.autodoc')
# inject a navdoc from the last header/footer page, to the
# extended autodocs start page
def navdocs_transform(builder, docnames):
builder.state.register_title('_validation_prev', 'sphinx.ext.todo',
None)
docnames.insert(0, '_validation_prev')
return docnames
config['confluence_navdocs_transform'] = navdocs_transform
dataset = os.path.join(self.datasets, 'extended-autodocs')
doc_dir = prepare_dirs('validation-set-extended-autodocs')
xml_dir = os.path.join(dataset, 'xml')
config['breathe_projects'] = {}
for name in os.listdir(xml_dir):
sample_dir = os.path.join(xml_dir, name)
if os.path.isdir(sample_dir):
config['breathe_projects'][name] = sample_dir
build_sphinx(dataset, config=config, out_dir=doc_dir)
def process_raw_upload(target_sandbox):
test_dir = os.path.dirname(os.path.realpath(__file__))
base_dir = os.path.join(test_dir, os.pardir)
sandbox_dir = os.path.join(base_dir, target_sandbox)
raw_file = os.path.join(sandbox_dir, 'raw.conf')
if not os.path.exists(raw_file):
print('[sandbox] missing file', raw_file)
return
doc_dir = prepare_dirs('sandbox-raw')
with prepare_sphinx(sandbox_dir, out_dir=doc_dir, relax=True) as app:
publisher = ConfluencePublisher()
publisher.init(app.config)
publisher.connect()
while True:
data = {
'labels': [],
}
with io.open(raw_file, 'r', encoding='utf-8') as f:
data['content'] = f.read()
print('[sandbox] publishing page...')
try:
publisher.store_page('raw', data)
except ConfluenceBadApiError as ex:
print('[sandbox] failed to publish content:', ex)
print('[sandbox] any key to retry; q to quit')
if input().lower() == 'q':
break
def test_nonjsonresponse(self):
config = dict(self.config)
config['confluence_server_url'] = 'https://example.com/'
dataset = os.path.join(self.datasets, 'base')
doc_dir = prepare_dirs('validation-set-nonjsonresponse')
with self.assertRaises(ConfluenceBadApiError):
build_sphinx(dataset, config=config, out_dir=doc_dir)
def test_hierarchy(self):
config = dict(self.config)
config['confluence_max_doc_depth'] = 2
config['confluence_page_hierarchy'] = True
dataset = os.path.join(self.datasets, 'hierarchy')
doc_dir = prepare_dirs('validation-set-hierarchy')
build_sphinx(dataset, config=config, out_dir=doc_dir)
def test_header_footer(self):
config = dict(self.config)
dataset = os.path.join(self.datasets, 'header-footer')
doc_dir = prepare_dirs('validation-set-hf')
config['confluence_header_file'] = os.path.join(dataset, 'header.tpl')
config['confluence_footer_file'] = os.path.join(dataset, 'footer.tpl')
build_sphinx(dataset, config=config, out_dir=doc_dir)
def process_sandbox(target_sandbox, builder=None, defines=None):
test_dir = os.path.dirname(os.path.realpath(__file__))
base_dir = os.path.join(test_dir, os.pardir)
sandbox_dir = os.path.join(base_dir, target_sandbox)
container = 'sandbox-test'
if builder:
container += '-' + builder
doc_dir = prepare_dirs(container)
build_sphinx(sandbox_dir, out_dir=doc_dir, builder=builder,
extra_config=defines, relax=True)
def test_standard_macro_restricted(self):
config = dict(self.config)
dataset = os.path.join(self.datasets, 'standard')
doc_dir = prepare_dirs('validation-set-standard-nm')
config['confluence_adv_restricted'] = [
'anchor',
'children',
'code',
'info',
'viewfile',
'jira'
]
config['confluence_header_file'] = os.path.join(dataset, 'no-macro.tpl')
config['confluence_publish_postfix'] = ' (nomacro)'
build_sphinx(dataset, config=config, out_dir=doc_dir)
def test_extensions(self):
config = dict(self.config)
config['extensions'].append('sphinx.ext.autodoc')
config['extensions'].append('sphinx.ext.autosummary')
config['extensions'].append('sphinx.ext.graphviz')
config['extensions'].append('sphinx.ext.ifconfig')
config['extensions'].append('sphinx.ext.inheritance_diagram')
config['extensions'].append('sphinx.ext.todo')
config['graphviz_output_format'] = 'svg'
config['todo_include_todos'] = True
config['todo_link_only'] = True
dataset = os.path.join(self.datasets, 'extensions')
doc_dir = prepare_dirs('validation-set-extensions')
sys.path.insert(0, os.path.join(dataset, 'src'))
build_sphinx(dataset, config=config, out_dir=doc_dir)
sys.path.pop(0)
def test_standard_default(self):
config = self.config.clone()
config['confluence_sourcelink']['container'] += 'standard/'
dataset = os.path.join(self.datasets, 'standard')
doc_dir = prepare_dirs('validation-set-standard')
# inject a navdoc to the header/footer start page
def navdocs_transform(builder, docnames):
builder.state.register_title('_validation_prev', self.test_key,
None)
docnames.insert(0, '_validation_prev')
builder.state.register_title('_validation_next',
'Header/footer example', None)
docnames.append('_validation_next')
return docnames
config['confluence_navdocs_transform'] = navdocs_transform
build_sphinx(dataset, config=config, out_dir=doc_dir)
def test_markdown(self):
config = self.config.clone()
config['confluence_sourcelink']['container'] += 'markdown/'
config['extensions'].append('myst_parser')
dataset = os.path.join(self.datasets, 'markdown')
doc_dir = prepare_dirs('validation-set-markdown')
# inject a navdoc from the last hierarchy example page, to the
# extensions start page
def navdocs_transform(builder, docnames):
builder.state.register_title('_validation_prev',
'Hierarchy example (d)', None)
docnames.insert(0, '_validation_prev')
builder.state.register_title('_validation_next', 'Extensions',
None)
docnames.append('_validation_next')
return docnames
config['confluence_navdocs_transform'] = navdocs_transform
build_sphinx(dataset, config=config, out_dir=doc_dir)
def test_hierarchy(self):
config = self.config.clone()
config['confluence_max_doc_depth'] = 2
config['confluence_page_hierarchy'] = True
config['confluence_sourcelink']['container'] += 'hierarchy/'
# inject a navdoc from the last "Header/footer" page, to the
# markdown start page
def navdocs_transform(builder, docnames):
builder.state.register_title('_validation_prev',
'Header/footer example (page c)',
None)
docnames.insert(0, '_validation_prev')
builder.state.register_title('_validation_next', 'Markdown', None)
docnames.append('_validation_next')
return docnames
config['confluence_navdocs_transform'] = navdocs_transform
dataset = os.path.join(self.datasets, 'hierarchy')
doc_dir = prepare_dirs('validation-set-hierarchy')
build_sphinx(dataset, config=config, out_dir=doc_dir, relax=True)
def test_header_footer(self):
config = self.config.clone()
config['confluence_sourcelink']['container'] += 'header-footer/'
dataset = os.path.join(self.datasets, 'header-footer')
doc_dir = prepare_dirs('validation-set-hf')
config['confluence_header_file'] = os.path.join(dataset, 'header.tpl')
config['confluence_footer_file'] = os.path.join(dataset, 'footer.tpl')
# inject a navdoc from the last "standard" page, to the
# hierarchy example start page
def navdocs_transform(builder, docnames):
builder.state.register_title('_validation_prev',
'Verification of content', None)
docnames.insert(0, '_validation_prev')
builder.state.register_title('_validation_next',
'Hierarchy example', None)
docnames.append('_validation_next')
return docnames
config['confluence_navdocs_transform'] = navdocs_transform
build_sphinx(dataset, config=config, out_dir=doc_dir)
def setUpClass(cls):
enable_sphinx_info()
# build configuration
space_key = os.getenv(SPACE_ENV_KEY, DEFAULT_TEST_SPACE)
cls.config = prepare_conf()
cls.config['confluence_disable_notifications'] = True
cls.config['confluence_page_hierarchy'] = True
cls.config['confluence_page_generation_notice'] = True
cls.config['confluence_parent_page'] = None
cls.config['confluence_prev_next_buttons_location'] = 'both'
cls.config['confluence_publish'] = True
cls.config['confluence_server_pass'] = os.getenv(AUTH_ENV_KEY)
cls.config['confluence_server_url'] = DEFAULT_TEST_URL
cls.config['confluence_server_user'] = DEFAULT_TEST_USER
cls.config['confluence_sourcelink'] = {
'type': 'github',
'owner': 'sphinx-contrib',
'repo': 'confluencebuilder',
'container': 'tests/validation-sets/',
}
cls.config['confluence_space_key'] = space_key
cls.config['confluence_timeout'] = 10
cls.config['imgmath_font_size'] = 14
cls.config['imgmath_image_format'] = 'svg'
cls.config['imgmath_use_preview'] = True
cls.config['manpages_url'] = 'https://example.org/{path}'
cls.test_desc = os.getenv(TESTDESC_ENV_KEY, DEFAULT_TEST_DESC)
cls.test_key = os.getenv(TESTKEY_ENV_KEY, DEFAULT_TEST_KEY)
cls.test_version = os.getenv(TESTKEY_ENV_KEY, DEFAULT_TEST_VERSION)
# overrides from user
try:
from validation_test_overrides import config_overrides
cls.config.update(config_overrides)
except ImportError:
pass
try:
from validation_test_overrides import config_test_desc
cls.test_desc = config_test_desc
except ImportError:
pass
try:
from validation_test_overrides import config_test_key
cls.test_key = config_test_key
except ImportError:
pass
try:
from validation_test_overrides import config_test_version
cls.test_version = config_test_version
except ImportError:
pass
# finalize
if cls.config['confluence_space_key'].startswith('~'):
cls.config['confluence_root_homepage'] = False
cls.config['confluence_publish_prefix'] = ''
cls.config['confluence_publish_postfix'] = ''
cls.config['confluence_purge'] = False
cls.config['confluence_sourcelink']['version'] = cls.test_version
cls.config['rst_epilog'] = """
.. |test_key| replace:: {}
.. |test_desc| replace:: {}
""".format(cls.test_key, cls.test_desc)
# find validate-sets base folder
test_dir = os.path.dirname(os.path.realpath(__file__))
cls.datasets = os.path.join(test_dir, 'validation-sets')
# setup base structure
dataset = os.path.join(cls.datasets, 'base')
doc_dir = prepare_dirs('validation-set-base')
config = cls.config.clone()
config['confluence_sourcelink']['container'] += 'base/'
# inject a navdoc from the "standard" start page
def navdocs_transform(builder, docnames):
builder.state.register_title('_validation_next', 'Standard', None)
docnames.append('_validation_next')
return docnames
config['confluence_navdocs_transform'] = navdocs_transform
# build/publish test base page
build_sphinx(dataset, config=config, out_dir=doc_dir)
# finalize configuration for tests
cls.config['confluence_parent_page'] = cls.test_key
cls.config['confluence_purge'] = True
cls.config['confluence_purge_from_root'] = True
cls.config['confluence_root_homepage'] = False
def setUpClass(cls):
enable_sphinx_info()
# build configuration
cls.config = prepare_conf()
cls.config['confluence_disable_notifications'] = True
cls.config['confluence_page_hierarchy'] = True
cls.config['confluence_parent_page'] = None
cls.config['confluence_publish'] = True
cls.config['confluence_space_name'] = os.getenv(
SPACE_ENV_KEY, DEFAULT_TEST_SPACE)
cls.config['confluence_server_pass'] = os.getenv(AUTH_ENV_KEY)
cls.config['confluence_server_url'] = DEFAULT_TEST_URL
cls.config['confluence_server_user'] = DEFAULT_TEST_USER
cls.config['confluence_timeout'] = 1
cls.config['imgmath_font_size'] = 14
cls.config['imgmath_image_format'] = 'svg'
cls.config['imgmath_use_preview'] = True
cls.config['manpages_url'] = 'https://example.org/{path}'
cls.test_desc = os.getenv(TESTDESC_ENV_KEY, DEFAULT_TEST_DESC)
cls.test_key = os.getenv(TESTKEY_ENV_KEY, DEFAULT_TEST_KEY)
# overrides from user
try:
from validation_test_overrides import config_overrides
cls.config.update(config_overrides)
except ImportError:
pass
try:
from validation_test_overrides import config_test_desc
cls.test_desc = config_test_desc
except ImportError:
pass
try:
from validation_test_overrides import config_test_key
cls.test_key = config_test_key
except ImportError:
pass
# finalize
if cls.config['confluence_space_name'].startswith('~'):
cls.config['confluence_master_homepage'] = False
else:
cls.config['confluence_master_homepage'] = True
cls.config['confluence_publish_prefix'] = ''
cls.config['confluence_publish_postfix'] = ''
cls.config['confluence_purge'] = False
cls.config['rst_epilog'] = """
.. |test_key| replace:: {}
.. |test_desc| replace:: {}
""".format(cls.test_key, cls.test_desc)
# find validate-sets base folder
test_dir = os.path.dirname(os.path.realpath(__file__))
cls.datasets = os.path.join(test_dir, 'validation-sets')
# setup base structure
dataset = os.path.join(cls.datasets, 'base')
doc_dir = prepare_dirs('validation-set-base')
# build/publish test base page
build_sphinx(dataset, config=cls.config, out_dir=doc_dir)
# finalize configuration for tests
cls.config['confluence_master_homepage'] = False
cls.config['confluence_parent_page'] = cls.test_key
cls.config['confluence_prev_next_buttons_location'] = 'both'
cls.config['confluence_purge'] = True
cls.config['confluence_purge_from_master'] = True
def test_standard_default(self):
dataset = os.path.join(self.datasets, 'standard')
doc_dir = prepare_dirs('validation-set-standard')
build_sphinx(dataset, config=self.config, out_dir=doc_dir)