Improving Custom PyPI Theme Support In Yaydoc
Yaydoc has been supporting custom themes from nearly it’s inception. Themes, which it could not find locally, it would automatically try to install it via pip and set up appropriate metadata about the themes in the generated conf.py. It was one of the first major enhancement we provided as compared to when using bare sphinx to generate documentation. Since then, a large number of features have been added to ease the process of documentation generation but the core theming aspects have remained unchanged. To use a theme, sphinx needs the exact name of the theme and the absolute path to it. To obtain these metadata, the existing implementation accessed the __file__ attribute of the imported package to get the absolute path to the __init__.py file, a necessary element of all python packages. From there we searched for a file named theme.conf, and thus the directory containing that file was our required theme. There were a few mistakes in our earlier implementation. For starters, we assumed that the distribution name of the theme in PyPI and the package name which should be imported would be same. This is generally true but is not necessary. One such theme from PyPI is Flask-Sphinx-Themes. While you need to install it using pip install Flask-Sphinx-Themes yet to import it in a module one needs to import flask_sphinx_themes This lead to build errors when specific themes like this was used. To solve this, we used the pkg_resources package. It allows us to get various metadata about a package in an abstract way without needing to specifically handle if the package is zipped or not. try: dist = pkg_resources.get_distribution('{{ html_theme }}') top_level = list(dist._get_metadata('top_level.txt'))[0] dist_path = os.path.join(dist.location, top_level) except (pkg_resources.DistributionNotFound, IndexError): print("\nError with distribution {0}".format('{{ html_theme }}')) html_theme = 'fossasia_theme' html_theme_path = ['_themes'] The idea here is that instead of searching for __init__.py, we read the name of the top_level directory using the first entry of the top_level.txt, a file created by setuptools when installing the package. We build the path by joining the location attribute of the Distribution object and the name of the top_level directory. The advantage with this approach is that we don’t need to import anything and thus no longer need to know the exact package name. With this update, Support for custom themes has been greatly increased. Resources Sphinx - Documentation Generator Setuptools - Official Documentation