Consider a generic Directive as the basis for a new extension. I’ll only show the code that elicits an error.
import docutils.nodes
from docutils import nodes, core
import docutils.nodes
from docutils.parsers.rst import Directive, directives
from pathlib import Path
class TestDirective(Directive):
''' Return the last two parts of the Path for each document that is processed. Do other cool stuff.'''
has_content = True
standard_include_path = Path(states.__file__).parent / 'include'
option_spec = {'file': directives.path,
'url': directives.uri,
'encoding': directives.encoding,
'class': directives.class_option}
def run(self):
# Next line is key to solving the problem
current_source = self.state.document.current_source
# Add error handling solution here
# Do some path manipulation
full_filepath = Path(current_source)
filepath_no_suffix = full_filepath.with_suffix('')
filepath = filepath_no_suffix.parts[-2:]
# View the last two parts of the file path of file being processed
# Purpose - Build a URL path; first, print path before assigning it to a variable.
url_path = Path(*filepath)
print("URL",url_path)
# Other code follows to traverse docutils.nodes and extract data.
# [...]
def setup(app):
# Register custom directive
app.add_directive("testdirective", TestDirective)
Assumptions
- Items added in conf.py
sys.path.append(os.path.abspath('../_ext'))
- testdirective was added to
extensions
- Using
Sphinx 4.2.0
- Using
Python3.10
- Using a custom Makefile that supports
make build
andmake clean
targets - Using a
sphinx-quickstart
where only 3 docs were added; used as source dir- Directory structure:
source/
guides/
overview.rst
get_started.rst
developer_guide.rst
- Directory structure:
Expected output
In summary, every line should show some “URL directory/document”
URL guides/overview7%] guides/overview
URL guides/get_started9%] guides/get_started
URL guides/developer_guide26%] guides/developer_guide
Error output
A error occurs on line 1.
This may be due to Sphinx pulling in substitutions from the rst_epilog
in conf.py. I’m not sure.
URL <rst_epilog>
URL guides/get_started9%] guides/get_started
URL guides/developer_guide26%] guides/developer_guide
Error Inquiry
In the Error Output, line 1, instead of producing a filepath, it produces <rst_epilog>
.
I need to code some error handling to make sure that if the builder encounters this type of message, it can revert to the parent filename. Does anyone have any insight on how to solve this?
What I’ve tried
I’ve been hacking on including some variaton of the class Include(Directive), here: https://sphinx-docutils.readthedocs.io/en/latest/_modules/docutils/parsers/rst/directives/misc.html#
So far, I tried to insert the following code where comment “Add error handling solution here” appears, but nothing works.
Example attempt to solve error:
current_source = self.state.document.current_source
path = directives.path(self.arguments[0])
if path.startswith('<') and path.endswith('>'):
_base = self.standard_include_path
path = path[1:-1]
else:
_base = Path(current_source).parent
path = utils.relative_path(None, _base/path)
Yet, if I add the above code, I receive the following error:
path = directives.path(self.arguments[0])
IndexError: list index out of range