ignacysokolowski/sphinx-readable-theme

A clean and readable Sphinx theme with focus on autodoc -- documentation from docstrings

sphinx-readable-theme's Issues

[BUG]Fail to create rpm using Python2 & Python3

Issue:
we can install the package using pip and it's great. However I need rpm so that I can install using yum.

Traceback

error: line 14: Unknown tag: Permission is hereby granted, free of charge, to any person obtaining a copy
error: query of specfile build/bdist.linux-x86_64/rpm/SPECS/sphinx-readable-theme.spec failed, can't parse
error: Failed to execute: "rpm -q --qf '%{name}-%{version}-%{release}.src.rpm %{arch}/%{name}-%{version}-%{release}.%{arch}.rpm\\n' --specfile 'build/bdist.linux-x86_64/rpm/SPECS/sphinx-readable-theme.spec'"

Description:
I have a requirement to install the package in the chroot dir where I do not have pip/easy_install installed. I have installed most of the python dependent packages/rpms using yum but when I come to install python2-sphinx-readable-theme, I do not see any entry in the rpmfind database.

I can do it manually while forking the repo and build rpm that satisfie my need but since most of the packages have corresponding rpm entry into the db, would be great to have this there too.

Proposed Solution
I think we should have rpm package as well like this
python2-sphinx-readable-theme
python3-sphinx-readable-theme

Would love to hear if there is any issue to create corresponding rpm and register same to the distro db.

Distro: Fedora 29
Python 3.7.x, 2.7.x

sphinx warnings `reference target not found`

First of all currently it is not possible to use straight sphinx-build command to build documentation out of source tree

+ /usr/bin/sphinx-build -n -T -b man docs/source build/sphinx/man
Running Sphinx v4.5.0

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/conf.py", line 11, in <module>
    import sphinx_readable_theme
ModuleNotFoundError: No module named 'sphinx_readable_theme'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/cmd/build.py", line 272, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.8/site-packages/sphinx/application.py", line 202, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 165, in read
    namespace = eval_config_file(filename, tags)
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 345, in eval_config_file
    raise ConfigError(msg % traceback.format_exc()) from exc
sphinx.errors.ConfigError: There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/conf.py", line 11, in <module>
    import sphinx_readable_theme
ModuleNotFoundError: No module named 'sphinx_readable_theme'


Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/lib/python3.8/site-packages/sphinx/config.py", line 332, in eval_config_file
    exec(code, namespace)
  File "/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/conf.py", line 11, in <module>
    import sphinx_readable_theme
ModuleNotFoundError: No module named 'sphinx_readable_theme'

This can be fixed by patch like below:

--- a/docs/source/conf.py~      2022-05-27 12:57:20.000000000 +0000
+++ b/docs/source/conf.py       2022-05-27 13:00:31.935970748 +0000
@@ -8,12 +8,11 @@
 import os
 import sys

-import sphinx_readable_theme
-
-
 # Adding this directory to the sys path, to build autodoc of example module.
+sys.path.insert(0, os.path.abspath("../.."))
 sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))

+import sphinx_readable_theme

 # -- General configuration ----------------------------------------------------

This patch fixes what is in the comment and that can of fix is suggested in sphinx example copy.py https://www.sphinx-doc.org/en/master/usage/configuration.html#example-of-configuration-file

Than .. on building my packages I'm using sphinx-build command with -n switch which shows warmings about missing references. These are not critical issues.

Here is the output with warnings:

+ /usr/bin/sphinx-build -n -T -b man docs/source build/sphinx/man
Running Sphinx v4.5.0
making output directory... done
loading intersphinx inventory from http://docs.python.org/2.7/objects.inv...
intersphinx inventory has moved: http://docs.python.org/2.7/objects.inv -> https://docs.python.org/2.7/objects.inv
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-sphinx-readable-heme.3 { } /home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/example.py:docstring of example:3: WARNING: py:class reference target not found: Storage
/home/tkloczko/rpmbuild/BUILD/sphinx-readable-theme-1.3.0/docs/source/example.py:docstring of example:3: WARNING: py:func reference target not found: store_integers
done
build succeeded, 2 warnings.

You can peak on fixes that kind of issues in other projects
latchset/jwcrypto#289
click-contrib/sphinx-click@abc31069
latchset/jwcrypto#289
RDFLib/rdflib-sqlalchemy#95

No footer directives ignored...

Firstly, I want to say that you for doing a great job with this theme. However, it seems to have a small flaw.

I have the following directives in my conf.py file:

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
html_show_copyright = False

and, yet, this footer is shown
© Copyright 2016, André Roberge. Created using Sphinx 1.3.1.
when using your theme.