Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Source folder is always the same as conf.py folder #238

Closed
1 task
Predelnik opened this issue Oct 19, 2020 · 6 comments
Closed
1 task

Source folder is always the same as conf.py folder #238

Predelnik opened this issue Oct 19, 2020 · 6 comments
Labels
area:esbonio area:preview All issues related to preview.

Comments

@Predelnik
Copy link

Environment

  • [ 129.0.0 ] Extension version:
  • [ 1.50.1 ] Visual Studio Code version:
  • [ Windows 8.1] Operating System version:
  • [ 3.9 ] Python version:
  • [ 3.2.1 ] sphinx version:
  • A sample of conf.py or its important fragments:

Expected behavior

Source directory could be specified relative to conf.py but not always be the same as conf.py directory.

Actual behavior

Extension always runs sphinx with . as source path

I would suggest allowing specifying source folder in config just as config/build folders could be.

@lextm
Copy link
Member

lextm commented Oct 21, 2020

Can you provide a sample project on GitHub showing why you need a non default source path?

This extension does not mean to cover all Sphinx scenarios so its defaults match many recommended setup (like ReadTheDocs guides).

But if yours turns out to be a typical case that requires attention then some changes can be implemented.

@Lucide
Copy link

Lucide commented Oct 23, 2020

I got stuck in this too, I didn't even have to search!
I'm working on a CMake C project, the tree is roughly this:

.
├── cmake-build-debug-win
│   ├── doc
│   │   ├── conf.py //configured conf.py
│   │   ├── html(dir) //sphinx output dir
│   │   └── xml(dir) //doxygen output dir/breathe extension input dir
├── doc
│   ├── conf.py.in //template conf.py
│   ├── index.rst
│   └── static(dir)
├── venvWin(dir)
└── venvWsl(dir)

In CMake, you're expected to do "out of source builds", where the configure/build process leaves the project unchanged, and files are written under the build directory only (here cmake-build-debug-win).
The conf.py is one of those files that need to be "filled out" by CMake. The configured version is put in the respective build directory. This is a very common C/C++ project layout.
In this case, Sphinx's source folder should be ./doc/. I couldn't find a way to express that with the extension. This is what it does instead:

[Log - 12:28:57] [linter] Execute: "D:\Users\Nemo\Roaming\Python\Python39\Scripts\rstcheck.exe" "d:\Users\Nemo\OneDrive-shared\c\VisualT\doc\index.rst" in d:\Users\Nemo\OneDrive-shared\c\VisualT.
[Log - 12:30:18] Running cmd: "d:\Users\Nemo\OneDrive-shared\c\VisualT\venvWin\Scripts\python.exe" -c "import sphinx;"
[Log - 12:30:19] Successful exec
[Log - 12:30:19] [preview] Compiling file: d:\Users\Nemo\OneDrive-shared\c\VisualT\doc\index.rst
[Log - 12:30:19] [preview] Sphinx conf.py directory: d:\Users\Nemo\OneDrive-shared\c\VisualT\cmake-build-debug-win\doc
[Log - 12:30:19] [preview] Sphinx html directory: d:\Users\Nemo\OneDrive-shared\c\VisualT\cmake-build-debug-win\doc\html
[Log - 12:30:19] [preview] Compiler: "d:\Users\Nemo\OneDrive-shared\c\VisualT\venvWin\Scripts\python.exe" -m sphinx -b html . "d:\Users\Nemo\OneDrive-shared\c\VisualT\cmake-build-debug-win\doc\html"
[Log - 12:30:19] [preview] Working directory: d:\Users\Nemo\OneDrive-shared\c\VisualT\cmake-build-debug-win\doc
[Log - 12:30:19] [preview] HTML file: d:\Users\Nemo\OneDrive-shared\c\VisualT\cmake-build-debug-win\doc\index.html

Sphinx searches index.rst inside the build dir:

Error: Command failed: "d:\Users\Nemo\OneDrive-shared\c\VisualT\venvWin\Scripts\python.exe" -m sphinx -b html . "d:\Users\Nemo\OneDrive-shared\c\VisualT\cmake-build-debug-win\doc\html"

Sphinx error:
master file d:\Users\Nemo\OneDrive-shared\c\VisualT\cmake-build-debug-win\doc\index.rst not found

@Predelnik
Copy link
Author

@Lucide Thank you for providing a compelling example!

The project I'm working on is not open source unfortunately, and most of the open source projects I found during quick search indeed had con.py beside index.rst, so I was going to do a bit more thorough search on a week-end. But maybe this case already is enough to justify adding the option for this, @lextm?

@lextm lextm added area:preview All issues related to preview. in progress labels Oct 23, 2020
@lextm lextm added up for grab Pull requests are welcome. and removed in progress more info needed labels Mar 10, 2021
@brboi
Copy link

brboi commented Nov 18, 2021

Hello, another open source documentation project where this extension does not work with the same issue is https://github.com/odoo/documentation

@lextm
Copy link
Member

lextm commented Feb 27, 2022

With the recent change on live preview engine, this is going to be addressed soon.

@lextm
Copy link
Member

lextm commented Feb 27, 2022

Starting from release 172.0.0, you can use restructuredtext.sourcePath to specify the root directory of a sphinx project, in case it is different from restructuredtext.confPath.

@lextm lextm closed this as completed Feb 27, 2022
@lextm lextm added area:esbonio and removed up for grab Pull requests are welcome. labels Feb 27, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:esbonio area:preview All issues related to preview.
Projects
None yet
Development

No branches or pull requests

4 participants