docs.py 1.2 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344
  1. """Build QMK documentation locally
  2. """
  3. import shutil
  4. from pathlib import Path
  5. from subprocess import DEVNULL
  6. from milc import cli
  7. DOCS_PATH = Path('docs/')
  8. BUILD_PATH = Path('.build/')
  9. BUILD_DOCS_PATH = BUILD_PATH / 'docs'
  10. DOXYGEN_PATH = BUILD_PATH / 'doxygen'
  11. MOXYGEN_PATH = BUILD_DOCS_PATH / 'internals'
  12. @cli.subcommand('Build QMK documentation.', hidden=False if cli.config.user.developer else True)
  13. def generate_docs(cli):
  14. """Invoke the docs generation process
  15. TODO(unclaimed):
  16. * [ ] Add a real build step... something static docs
  17. """
  18. if BUILD_DOCS_PATH.exists():
  19. shutil.rmtree(BUILD_DOCS_PATH)
  20. if DOXYGEN_PATH.exists():
  21. shutil.rmtree(DOXYGEN_PATH)
  22. shutil.copytree(DOCS_PATH, BUILD_DOCS_PATH)
  23. # When not verbose we want to hide all output
  24. args = {
  25. 'capture_output': False if cli.config.general.verbose else True,
  26. 'check': True,
  27. 'stdin': DEVNULL,
  28. }
  29. cli.log.info('Generating docs...')
  30. # Generate internal docs
  31. cli.run(['doxygen', 'Doxyfile'], **args)
  32. cli.run(['moxygen', '-q', '-g', '-o', MOXYGEN_PATH / '%s.md', DOXYGEN_PATH / 'xml'], **args)
  33. cli.log.info('Successfully generated docs to %s.', BUILD_DOCS_PATH)