mdolab / mdolab/pyXDSM

Better error messages and documentation for dependencies

Open
#51 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
74
Forks
51
PR merge metrics
No merged PRs in 30d

Description

Description of the issue

So, as a user of Overleaf, and thus not having a local LaTeX distribution installed, the first time trying to use this package didn't work. I found it out quite quickly by taking a quick peak in the sourcecode, however the package documentation doesn't appear to really mention the requirements of having a LaTeX distribution installed, and the error you get is a very undescriptive FileNotFoundError with nothing pointing to what exact file it is missing.

The error message I got:

Traceback (most recent call last):
  File "C:\Users\username\path\to\file.py", line 200, in <module>
    x.write("xdsm", cleanup=True, quiet=True)
  File "C:\Python310\lib\site-packages\pyxdsm\XDSM.py", line 628, in write 
    subprocess.run(command, check=True)
  File "C:\Python310\lib\subprocess.py", line 501, in run
    with Popen(*popenargs, **kwargs) as process:
  File "C:\Python310\lib\subprocess.py", line 966, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
  File "C:\Python310\lib\subprocess.py", line 1435, in _execute_child
    hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
FileNotFoundError: [WinError 2] The system cannot find the file specified 

Potential solution

Solving the issue would be two-fold. Firstly, the error message should be more descriptive. An error message saying pdfLaTeX wasent found would be a lot more helpful.

Secondly, the "installation" documentation should mention a LaTeX environment is required for proper operation.

I would be happy to look into making a PR for this if this would be desired.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at pyxdsm/XDSM.py around line 628 and inspect the subprocess invocation that produces the missing-file error. Then locate the installation documentation and verify it states that a LaTeX environment is required. Done means the missing pdfLaTeX condition yields a descriptive message and the requirement is documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
latex, python
Domain
documentation, tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.