backstage: Generating techdocs from a provided example within docker container doesn't work
Expected Behavior
When clicking on the READ DOCS link that is generated using this example in the Documentation, the techdocs are properly displayed.
Current Behavior
│ 2021-05-18T09:46:09.006Z techdocs info Step 2 of 3: Generating docs for entity Component:default/documented-component type=plugin
2021-05-18T09:46:09.688Z techdocs error Build failed with error: DEBUG - Loading configuration file: /tmp/backstage-rKimYx/mkdocs.yml,DEBUG - Loaded theme configuration for 'mkdocs' from '/usr
/local/lib/python3.7/dist-packages/mkdocs/themes/mkdocs/mkdocs_theme.yml': {'static_templates': ['404.html'], 'include_search_page': False, 'search_index_only': False, 'highlightjs': True, 'hljs_lan
guages': [], 'hljs_style': 'github', 'navigation_depth': 2, 'nav_style': 'primary', 'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}},DEBUG - Config value: 'config_file_path'
= '/tmp/backstage-rKimYx/mkdocs.yml'
DEBUG - Config value: 'site_name' = 'Example Documentation'
DEBUG - Config value: 'nav' = [{'Home': 'index.md'}, {'Subpage': 'sub-page.md'}, {'Code Sample': 'code/code-sample.md'}, {'Extensions': 'extensions.md'}]
DEBUG - Config value: 'pages' = None,DEBUG - Config value: 'site_url' = '',DEBUG - Config value: 'site_description' = None
DEBUG - Config value: 'site_author' = None,DEBUG - Config value: 'theme' = Theme(name='mkdocs', dirs=['/usr/local/lib/python3.7/dist-packages/mkdocs/themes/mkdocs', '/usr/local/lib/python3.7/d
ist-packages/mkdocs/templates'], static_templates=['sitemap.xml', '404.html'], include_search_page=False, search_index_only=False, highlightjs=True, hljs_languages=[], hljs_style='github', navigatio
n_depth=2, nav_style='primary', shortcuts={'help': 191, 'next': 78, 'previous': 80, 'search': 83}),DEBUG - Config value: 'docs_dir' = '/tmp/backstage-rKimYx/docs',DEBUG - Config value: 'site_d
ir' = '/tmp/techdocs-tmp-lYizwR'
DEBUG - Config value: 'copyright' = None,DEBUG - Config value: 'google_analytics' = None
DEBUG - Config value: 'dev_addr' = Address(host='127.0.0.1', port=8000),DEBUG - Config value: 'use_directory_urls' = True,DEBUG - Config value: 'repo_url' = '',DEBUG - Config value: 'rep
o_name' = '',DEBUG - Config value: 'edit_uri' = '',DEBUG - Config value: 'extra_css' = [],DEBUG - Config value: 'extra_javascript' = [],DEBUG - Config value: 'extra_templates' = [],DEBUG
- Config value: 'markdown_extensions' = ['toc', 'tables', 'fenced_code']
DEBUG - Config value: 'mdx_configs' = {},DEBUG - Config value: 'strict' = False,DEBUG - Config value: 'remote_branch' = 'gh-pages',DEBUG - Config value: 'remote_name' = 'origin',DEBUG
- Config value: 'extra' = {},DEBUG - Config value: 'plugins' = PluginCollection([('techdocs-core', <src.core.TechDocsCore object at 0x7f099dfe5278>)]),DEBUG - Loaded theme configuration for '
material' from '/usr/local/lib/python3.7/dist-packages/material/mkdocs_theme.yml': {'language': 'en', 'direction': None, 'features': [], 'palette': {'primary': None, 'accent': None}, 'font': {'text'
: 'Roboto', 'code': 'Roboto Mono'}, 'icon': None, 'favicon': 'assets/images/favicon.png', 'include_search_page': False, 'search_index_only': True, 'static_templates': ['404.html']},INFO - Cleani
ng site directory,INFO - Building documentation to directory: /tmp/techdocs-tmp-lYizwR,DEBUG - Reading markdown pages.
DEBUG - Reading: index.md,DEBUG - Reading: extensions.md,ERROR - Error reading page 'extensions.md': Failed to run plantuml: [Errno 2] No such file or directory: 'plantuml': 'plantuml',Trac
eback (most recent call last):
File "/usr/local/lib/python3.7/dist-packages/plantuml_markdown.py", line 268, in _render_local_uml_image
p = Popen(cmdline, stdin=PIPE, stdout=PIPE, stderr=PIPE, shell=(os.name == 'nt'))
File "/usr/lib/python3.7/subprocess.py", line 775, in __init__
restore_signals, start_new_session)
File "/usr/lib/python3.7/subprocess.py", line 1522, in _execute_child
raise child_exception_type(errno_num, err_msg, err_filename)
FileNotFoundError: [Errno 2] No such file or directory: 'plantuml': 'plantuml'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "/usr/local/bin/mkdocs", line 10, in <module>
sys.exit(cli())
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1134, in __call__
return self.main(*args, **kwargs)
│ return self.main(*args, **kwargs)
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1059, in main
rv = self.invoke(ctx)
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1665, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 1401, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python3.7/dist-packages/click/core.py", line 767, in invoke
return __callback(*args, **kwargs)
File "/usr/local/lib/python3.7/dist-packages/mkdocs/__main__.py", line 152, in build_command
build.build(config.load_config(**kwargs), dirty=not clean)
File "/usr/local/lib/python3.7/dist-packages/mkdocs/commands/build.py", line 271, in build
_populate_page(file.page, config, files, dirty)
File "/usr/local/lib/python3.7/dist-packages/mkdocs/commands/build.py", line 171, in _populate_page
page.render(config, files)
File "/usr/local/lib/python3.7/dist-packages/mkdocs/structure/pages.py", line 175, in render
self.content = md.convert(self.markdown)
File "/usr/local/lib/python3.7/dist-packages/markdown/core.py", line 260, in convert
self.lines = prep.run(self.lines)
File "/usr/local/lib/python3.7/dist-packages/plantuml_markdown.py", line 124, in run
text1, idx1 = self._replace_block(text[idx:])
File "/usr/local/lib/python3.7/dist-packages/plantuml_markdown.py", line 181, in _replace_block
diagram = self._render_diagram(code, requested_format)
File "/usr/local/lib/python3.7/dist-packages/plantuml_markdown.py", line 253, in _render_diagram
diagram = self._render_local_uml_image(code, requested_format)
File "/usr/local/lib/python3.7/dist-packages/plantuml_markdown.py", line 271, in _render_local_uml_image
raise Exception('Failed to run plantuml: %s' % exc)
Exception: Failed to run plantuml: [Errno 2] No such file or directory: 'plantuml': 'plantuml' type=plugin
2021-05-18T09:46:09.689Z backstage error Failed to generate docs from /tmp/backstage-rKimYx into /tmp/techdocs-tmp-lYizwR with error undefined type=errorHandler stack=Error: Failed to generate docs
from /tmp/backstage-rKimYx into /tmp/techdocs-tmp-lYizwR with error undefined
at TechdocsGenerator.run (/app/node_modules/@backstage/techdocs-common/dist/index.cjs.js:213:13)
at runMicrotasks (<anonymous>)
at processTicksAndRejections (internal/process/task_queues.js:95:5)
at async DocsBuilder.build (/app/node_modules/@backstage/plugin-techdocs-backend/dist/index.cjs.js:99:5)
at async /app/node_modules/@backstage/plugin-techdocs-backend/dist/index.cjs.js:214:9
Content from mentioned directorie /tmp/backstage-rKimYx
|-- catalog-info.yaml
|-- docs
| |-- code
| | `-- code-sample.md
| |-- extensions.md
| |-- images
| | `-- backstage-logo-cncf.svg
| |-- index.md
| `-- sub-page.md
`-- mkdocs.yml
Possible Solution
Steps to Reproduce
- Create the app using
yarn backstage-create-app - Add default example to the locations in
app-config.yaml:
- type: url
target: https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/examples/documented-component/catalog-info.yaml
- Use local setup:
techdocs:
builder: 'local' # Alternatives - 'external'
generators:
techdocs: 'local' # Alternatives - 'docker'
publisher:
type: 'local' # Alternatives - 'googleGcs' or 'awsS3' or 'azureBlobStorage' or 'openStackSwift'. Read documentation for using alternatives.
- Build docker image with mkdocs-techdocs-core==0.0.16 and start it. Alternatevily, start the backend locally with the mkdocs-techdocs-core==0.0.16 installed using pip.
Context
See above.
Your Environment
- NodeJS Version (v12): v14
- Operating System and Version (e.g. Ubuntu 14.04): using default Dockerfile, image running on AKS
- Used master branch for building, latest commit https://github.com/backstage/backstage/commit/f3f09dda341ff21fc1d55d088ee6698a638feb93
About this issue
- Original URL
- State: closed
- Created 3 years ago
- Comments: 16 (16 by maintainers)
@OrkoHunter @adrianke77 @emmaindal you won’t believe but it’s a one-liner 😮 Before:
RUN echo $'#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> /usr/local/bin/plantumlAfter:RUN echo '#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> /usr/local/bin/plantumlJust remove the first
$. It seems that these different base images are interpreting this line differently.@adrianke77 please test it and report back. If it works, the issue can be closed. Maybe it would make sense to include this Dockerfile somewhere in the documentation?
Looks like your Docker container doesn’t have plantuml installed. You can use the
techdocs-containerto see how to install that. (I’d recommend installing everything that’s in the techdocs-container)