ModuleNotFoundError: No module named 'documentation_helpers'

[pieterjanvc]

Bug description

Following the tutorial, I'm stuck at the first code block at the line

import documentation_helpers

I pip installed ragna successfully

How to reproduce the bug?

If I run this in python 3.10.12 on Ubuntu

import documentation_helpers

I get

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ModuleNotFoundError: No module named 'documentation_helpers'

Versions and dependencies used

Python 2.10.12
Ragna ragna 0.2.0
Ubuntu 22.04.2 LTS

Anything else?

No response

[pmeier]

The module you are looking for is here, but is not distributed with Ragna as it is only needed for the documentation. Could you tell us how you are interacting with the tutorial?

In the REST API tutorial there are two blocks that require the documentation_helpers:

1. To launch the REST API

   ragna/docs/tutorials/gallery_rest_api.py

   Lines 50 to 51 in aa2a702

   	rest_api = documentation_helpers.RestApi()
   	_ = rest_api.start(config)

   We explain above that outside of the documentation you would do this from another terminal

   ragna/docs/tutorials/gallery_rest_api.py

   Lines 22 to 30 in aa2a702

   	# ## Step 1: Start the REST API
   	#
   	# Ragnas REST API is normally started from a terminal with
   	#
   	# ```bash
   	# $ ragna api
   	# ```
   	#
   	# For this tutorial we use our helper that does the equivalent just from Python.

2. To upload a test document

   ragna/docs/tutorials/gallery_rest_api.py

   Lines 101 to 104 in aa2a702

   	document_name = "ragna.txt"
   	with open(documentation_helpers.assets / document_name, "rb") as file:
   	content = file.read()

   You can find this document here, but you could also use any other document.

[pmeier]

One option for us could be to just move the documentation helpers into ragna._docs. That way

1. we don't need to have extra files in the documentation that need to be included through sys.path, reducing the noise in the example
2. users can run the examples if they have Ragna installed
3. we are keeping the advantage of not being bound to BC compatibility even after we adopt semantic versioning given that the module is private.

I guess we could also ship the ragna.txt file given that it is not large.

[arjxn-py]

Hi there, I had also been trying to run this tutorial locally while setting up ragna.

Hence I tried to debug the issue and noticed that sys.path.insert(0, str(Path.cwd().parent)) is inserting an incorrect path if one is trying to run either of the gallery_python_api.py or gallery_rest_api.py from location other than docs/tutorials/ i.e. it is adding the path of the parent directory of cwd which should essentially point to docs/, but when trying to run tutorials from anywhere else it gets invalid (say from root, the path that gets added to to sys.path gets out of the project directory).

To fix this I replaced -

sys.path.insert(0, str(Path.cwd().parent))
import documentation_helpers

with -

cwd = Path(__file__).resolve().parent

while cwd:
    if (cwd / 'docs').is_dir():
        docs_path = cwd / 'docs'
        break
    cwd = cwd.parent

# If 'docs' directory is found, add it to the Python path
if docs_path:
    sys.path.insert(0, str(docs_path))

import documentation_helpers

But as @pmeier suggested moving the documentation helpers to ragna._docs is also a promising solution & I'd be really happy to assist the project try doing that & contribute to it further 🙂.
Thanks a lot 💐

[pmeier]

I'd be really happy to assist the project try doing that & contribute to it further 🙂.

Hi @arjxn-py 👋 We would love to have your contribution here. If you send a PR, tag me there so I can review it.

[pmeier]

@arjxn-py do you have a timeline for your contribution? I want to push a small bug fix release soon and this should be included.

[arjxn-py]

@arjxn-py do you have a timeline for your contribution? I want to push a small bug fix release soon and this should be included.

Apologies for the delay in response, I plan to fix this asap. I'm creating a branch & opening a PR to track progress in the meantime.