Cannot install Furo from source on Windows

[john-hen]

When running nox -s docs-live on Windows, Pip fails to install the Furo development version reporting NameError: name 'List' is not defined.

I'm on Windows 10, Python 3.9.9, and tried to follow the development workflow for Furo as described in the documentation. The latest commit, as of this writing, is f209987.

I installed NodeJS with the Windows installer currently recommended on the NodeJS download page. It's NodeJS 16.3.1, not NodeJS 12 as the Furo docs say. Older versions are available, but don't seem to come with an .msi installer, and I know of no reason why the newer (long-term support) version shouldn't work.

This is the output of my console session (cmd.exe run inside ConEmu):

Microsoft Windows [Version 10.0.19043.1348]

C:\temp
$ node --version
v16.13.1

C:\temp
$ npm --version
8.1.2

C:\temp
$ git clone https://github.com/pradyunsg/furo.git
Cloning into 'furo'...
remote: Enumerating objects: 23666, done.
remote: Counting objects: 100% (5716/5716), done.
remote: Compressing objects: 100% (1130/1130), done.
remote: Total 23666 (delta 3239), reused 5216 (delta 2866), pack-reused 17950
Receiving objects: 100% (23666/23666), 61.57 MiB | 11.41 MiB/s, done.
Resolving deltas: 100% (13016/13016), done.

C:\temp
$ cd furo

C:\temp\furo
$ npm install

added 245 packages, and audited 246 packages in 6s

38 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

C:\temp\furo
$ pip install nox
Collecting nox
  Using cached nox-2021.10.1-py3-none-any.whl (49 kB)
Requirement already satisfied: packaging>=20.9 in c:\programs\python\lib\site-packages (from nox) (21.3)
Collecting argcomplete<2.0,>=1.9.4
  Using cached argcomplete-1.12.3-py2.py3-none-any.whl (38 kB)
Requirement already satisfied: py<2.0.0,>=1.4.0 in c:\programs\python\lib\site-packages (from nox) (1.11.0)
Collecting virtualenv>=14.0.0
  Using cached virtualenv-20.10.0-py2.py3-none-any.whl (5.6 MB)
Collecting colorlog<7.0.0,>=2.6.1
  Using cached colorlog-6.6.0-py2.py3-none-any.whl (11 kB)
Requirement already satisfied: colorama in c:\programs\python\lib\site-packages (from colorlog<7.0.0,>=2.6.1->nox) (0.4.4)
Requirement already satisfied: pyparsing!=3.0.5,>=2.0.2 in c:\programs\python\lib\site-packages (from packaging>=20.9->nox) (3.0.6)
Requirement already satisfied: six<2,>=1.9.0 in c:\programs\python\lib\site-packages (from virtualenv>=14.0.0->nox) (1.16.0)
Collecting backports.entry-points-selectable>=1.0.4
  Using cached backports.entry_points_selectable-1.1.1-py2.py3-none-any.whl (6.2 kB)
Collecting distlib<1,>=0.3.1
  Using cached distlib-0.3.3-py2.py3-none-any.whl (496 kB)
Collecting filelock<4,>=3.2
  Using cached filelock-3.4.0-py3-none-any.whl (9.8 kB)
Requirement already satisfied: platformdirs<3,>=2 in c:\programs\python\lib\site-packages (from virtualenv>=14.0.0->nox) (2.4.0)
Installing collected packages: filelock, distlib, backports.entry-points-selectable, virtualenv, colorlog, argcomplete, nox
Successfully installed argcomplete-1.12.3 backports.entry-points-selectable-1.1.1 colorlog-6.6.0 distlib-0.3.3 filelock-3.4.0 nox-2021.10.1 virtualenv-20.10.0

C:\temp\furo
$ nox -s lint
nox > Running session lint
nox > Creating virtual environment (virtualenv) using python.exe in .nox\lint
nox > python -m pip install pre-commit
nox > pre-commit run --all-files
prettier.................................................................Passed
black....................................................................Passed
blacken-docs.............................................................Passed
isort....................................................................Passed
Check builtin type constructor use.......................................Passed
Check for added large files..............................................Passed
Check for case conflicts.................................................Passed
Check Toml...............................................................Passed
Check Yaml...............................................................Passed
Debug Statements (Python)................................................Passed
Fix End of Files.........................................................Passed
Forbid new submodules....................................................Passed
Trim Trailing Whitespace.................................................Passed
flake8...................................................................Passed
mypy.....................................................................Passed
pydocstyle...............................................................Passed
nox > Session lint was successful.

C:\temp\furo
$ nox -s docs-live
nox > Running session docs-live
nox > Creating virtual environment (virtualenv) using python.exe in .nox\docs-live
nox > python -m pip install -e .[doc] sphinx-theme-builder[cli]
nox > Command python -m pip install -e .[doc] sphinx-theme-builder[cli] failed with exit code 1:
Obtaining file:///C:/temp/furo
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Checking if build backend supports build_editable: started
  Checking if build backend supports build_editable: finished with status 'error'
  ERROR: Command errored out with exit status 1:
   command: 'C:\temp\furo\.nox\docs-live\Scripts\python.EXE' 'C:\temp\furo\.nox\docs-live\lib\site-packages\pip\_vendor\pep517\in_process\_in_process.py' _supported_features 'C:\Users\J\AppData\Local\Temp\tmpdzgcy43m'
       cwd: C:\temp\furo
  Complete output (26 lines):
  Traceback (most recent call last):
    File "C:\temp\furo\.nox\docs-live\lib\site-packages\pip\_vendor\pep517\in_process\_in_process.py", line 363, in <module>
      main()
    File "C:\temp\furo\.nox\docs-live\lib\site-packages\pip\_vendor\pep517\in_process\_in_process.py", line 345, in main
      json_out['return_val'] = hook(**hook_input['kwargs'])
    File "C:\temp\furo\.nox\docs-live\lib\site-packages\pip\_vendor\pep517\in_process\_in_process.py", line 112, in _supported_features
      backend = _build_backend()
    File "C:\temp\furo\.nox\docs-live\lib\site-packages\pip\_vendor\pep517\in_process\_in_process.py", line 89, in _build_backend
      obj = import_module(mod_path)
    File "C:\programs\Python\lib\importlib\__init__.py", line 127, in import_module
      return _bootstrap._gcd_import(name[level:], package, level)
    File "<frozen importlib._bootstrap>", line 1030, in _gcd_import
    File "<frozen importlib._bootstrap>", line 1007, in _find_and_load
    File "<frozen importlib._bootstrap>", line 986, in _find_and_load_unlocked
    File "<frozen importlib._bootstrap>", line 680, in _load_unlocked
    File "<frozen importlib._bootstrap_external>", line 850, in exec_module
    File "<frozen importlib._bootstrap>", line 228, in _call_with_frames_removed

    File "C:\Users\J\AppData\Local\Temp\pip-build-env-fb7usf7d\overlay\Lib\site-packages\sphinx_theme_builder\__init__.py", line 16, in <module>
      from ._internal.distributions import generate_metadata as _generate_metadata
    File "C:\Users\J\AppData\Local\Temp\pip-build-env-fb7usf7d\overlay\Lib\site-packages\sphinx_theme_builder\_internal\distributions.py", line 13, in <module>
      from .nodejs import generate_assets
    File "C:\Users\J\AppData\Local\Temp\pip-build-env-fb7usf7d\overlay\Lib\site-packages\sphinx_theme_builder\_internal\nodejs.py", line 18, in <module>
      from .passthrough import passthrough_run
    File "C:\Users\J\AppData\Local\Temp\pip-build-env-fb7usf7d\overlay\Lib\site-packages\sphinx_theme_builder\_internal\passthrough.py", line 96, in <module>
      def passthrough_run(args: List[str]) -> int:
  NameError: name 'List' is not defined
  ----------------------------------------
WARNING: Discarding file:///C:/temp/furo. Command errored out with exit status 1: 'C:\temp\furo\.nox\docs-live\Scripts\python.EXE' 'C:\temp\furo\.nox\docs-live\lib\site-packages\pip\_vendor\pep517\in_process\_in_process.py' _supported_features 'C:\Users\J\AppData\Local\Temp\tmpdzgcy43m' Check the logs for full command output.
ERROR: Command errored out with exit status 1: 'C:\temp\furo\.nox\docs-live\Scripts\python.EXE' 'C:\temp\furo\.nox\docs-live\lib\site-packages\pip\_vendor\pep517\in_process\_in_process.py' _supported_features 'C:\Users\J\AppData\Local\Temp\tmpdzgcy43m' Check the logs for full command output.
nox > Session docs-live failed.

[pradyunsg]

I need to cut a release of sphinx-theme-builder with pradyunsg/sphinx-theme-builder@e810420.

[pradyunsg]

Done!

[pradyunsg]

Try now, with sphinx-theme-builder 0.2.0a13!

[john-hen]

Some things work now that didn't before, but not all.

Running nox -s docs passes, though there are warnings.

Like these after "reading sources":

C:\temp\repos\furo\docs\kitchen-sink\demo.rst:265: WARNING: Footnote [4] is not referenced.
C:\temp\repos\furo\docs\kitchen-sink\demo.rst:271: WARNING: Footnote [11] is not referenced.
C:\temp\repos\furo\docs\kitchen-sink\demo.rst:16: WARNING: Undefined substitution referenced: "problematic".
C:\temp\repos\furo\docs\kitchen-sink\demo.rst:265: WARNING: Unknown target name: "5".
C:\temp\repos\furo\docs\kitchen-sink\demo.rst:308: WARNING: Unknown target name: "body elements".
C:\temp\repos\furo\docs\kitchen-sink\demo.rst:320: WARNING: Unknown target name: "hyperlink reference without a target".
C:\temp\repos\furo\docs\reference\hyperlinks.md:: WARNING: Duplicate explicit target name: "link".
C:\temp\repos\furo\docs\reference\hyperlinks.md:24: WARNING: Duplicate explicit target name: "link".

And these after "writing output":

C:\temp\repos\furo\docs\customisation\index.md:90: WARNING: 'any' reference target not found: customisation/injecting.md#injecting-code
C:\temp\repos\furo\docs\customisation\injecting.md:1: WARNING: 'myst' reference target not found: stablity
C:\temp\repos\furo\docs\customisation\logo.md:35: WARNING: 'myst' reference target not found: customisation/index.md#sidebar_hide_name
C:\temp\repos\furo\docs\customisation\sidebar.md:1: WARNING: 'myst' reference target not found: stablity
C:\temp\repos\furo\docs\kitchen-sink\demo.rst:279: WARNING: citation not found: nonexistent

But it builds. I can't navigate the local HTML pages in the browser, but that's probably because it's not being served via http: everything points to folders, not .html targets. So I guess that's normal.

However, the live build doesn't work on my end.

$ nox -s docs-live
nox > Running session docs-live
nox > Re-using existing virtual environment at .nox\docs-live.
nox > python -m pip install -e .[doc] sphinx-theme-builder[cli]
nox > stb serve docs/
[stb] Invoking sphinx-autobuild to run.
[sphinx-autobuild] pre-build
[sphinx-autobuild] > C:tempreposfuro.noxdocs-liveScriptspython.EXE -m sphinx_theme_builder compile
Traceback (most recent call last):
  File "C:\programs\Python\lib\runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\programs\Python\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "C:\temp\repos\furo\.nox\docs-live\lib\site-packages\sphinx_autobuild\__main__.py", line 5, in <module>
    main()
  File "C:\temp\repos\furo\.nox\docs-live\lib\site-packages\sphinx_autobuild\cli.py", line 191, in main
    builder()
  File "C:\temp\repos\furo\.nox\docs-live\lib\site-packages\sphinx_autobuild\build.py", line 57, in build
    subprocess.run(command, check=True)
  File "C:\programs\Python\lib\subprocess.py", line 505, in run
    with Popen(*popenargs, **kwargs) as process:
  File "C:\programs\Python\lib\subprocess.py", line 951, in __init__
    self._execute_child(args, executable, preexec_fn, close_fds,
  File "C:\programs\Python\lib\subprocess.py", line 1420, in _execute_child
    hp, ht, pid, tid = _winapi.CreateProcess(executable, args,
FileNotFoundError: [WinError 2] The system cannot find the file specified
error: autobuild-failed

× sphinx-autobuild exited with a non-zero exit code 1.
?-> See above for failure output from the underlying tooling.

Link: https://sphinx-theme-builder.rtfd.io/errors/#autobuild-failed
nox > Command stb serve docs/ failed with exit code 3
nox > Session docs-live failed.

I don't build Furo routinely, so may have missed something trivial. But I did follow the (updated) workflow to a T. The one thing that strikes me in that error message is the line [sphinx-autobuild] > C:tempreposfuro.noxdocs-liveScriptspython.EXE -m sphinx_theme_builder compile, where the full path to the command is missing the path separators.

[pradyunsg]

The warnings are expected. The generated site is built using dirhtml, so that sounds about right. You can use python -m http.server.

[pradyunsg]

That looks like a bug! Joys of not having a Windows machine to test it out. :)