elastic / elastic/docs

build_docs does not work for Windows

Open
#2,403 6 comments 0 reactions 0 assignees View on GitHub
>docs defer needs:triage Team:Docs
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.