build_docs does not work for Windows
- Dominant language
- Ruby
- Stars
- 265
- Forks
- 347
- Avg merge
- 3d 15h
- Merged PRs (30d)
- 2
Description
Requirements for local builds of docs are listed as Python 3 and Docker.
- https://github.com/elastic/docs/blob/master/README.asciidoc
There is no mentioned of OS requirements. Since Elasticsearch dev is supported on `Linux`, `Mac`, and `Windows`, my assumption is docs dev is supported on those same platforms.
However, when I try running build_docs in `Git Bash for Windows`, but I ran into issues. I can get build_docs to run, but it appears to have code which depends on `os.*` imports that are missing from `Python 3 for Windows` (https://www.python.org/downloads/).
Steps to reproduce:
1. Install Git Bash for Windows.
2. Install Python 3; check the option to add to Windows PATH.
3. Run Git Bash shell, and verify `python3 --version` works.
```
$ python3 --version
Python 3.10.3
$ python --version
Python 3.10.3
```
4. Clone two repos: `git clone git@github.com:elastic/docs.git` and `git clone git@github.com:elastic/elasticsearch.git`
5. Execute build_docs for an Elasticsearch index.asciidoc: `/c/GitHub/docs/build_docs --doc index.asciidoc --open`
```
Python was not found; run without arguments to install from the Microsoft Store, or disable this shortcut from Settings > Manage App Execution Aliases.
```
6. Open Windows settings, search for "Managed app execution aliases", disable Python and Python3, and re-run build_docs.
```
/usr/bin/env: 'python3': No such file or directory
```
7. Prepend python3 to the command: `python3 /c/GitHub/docs/build_docs --doc index.asciidoc --open`
```
Traceback (most recent call last):
File "C:\GitHub\docs\build_docs", line 20, in
from os import environ, getgid, getuid
ImportError: cannot import name 'getgid' from 'os' (C:\Users\JustinCranford\AppData\Local\Programs\Python\Python310\lib\os.py)
```
8. Edit build_docs to import all from `os`.
```
import os
#from os import environ, getgid, getuid
#from os.path import basename, dirname, exists, expanduser, isdir
#from os.path import join, normpath, realpath
```
9. Execute build_docs again: `python3 /c/GitHub/docs/build_docs --doc index.asciidoc --open`
```
Traceback (most recent call last):
File "C:\GitHub\docs\build_docs", line 35, in
DIR = dirname(realpath(__file__))
NameError: name 'dirname' is not defined
```
I can get build_docs to execute, but dependencies `os.getgit`, `os.getuid`, and `os.dirname` are not found.
***
Please update https://github.com/elastic/docs/blob/master/README.asciidoc with a workaround.
If it helps, some options might be:
1. If execution on Windows supported, fix cross-platform compatibility in build_docs, and add the `python3 cmd` and `Managed app execution aliases` workarounds to the README.
2. If execution on Windows is not supported, add a `docker run` command to bootstrap build_docs into a Linux container.
No code changes required, and Docker is already a dependency. This might be the easier option. Include cloning the repos, and mounting them into the container, plus a third mount for the output folder.
Thank you.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.