Error while building docs

[ManuelAlvarezC]

Originally submited by @cryptox31

• Commit SHA: ???
• Python version: ???
• Operating System: macOS

Description

Makefile crashes when building the documentation

What I Did

make install-develop
make docs

What I was expecting to get done

Build the docs

Additional context

➜  task-geo git:(cryptox31/fix/makefile) ✗ make docs
rm -f docs/api/*.rst
/Library/Developer/CommandLineTools/usr/bin/make -C docs clean 2>/dev/null  # this fails if sphinx is not yet installed
sphinx-apidoc --separate --no-toc -o docs/api/ task_geo
Creating file docs/api/task_geo.rst.
Creating file docs/api/task_geo.data_sources.rst.
Creating file docs/api/task_geo.data_sources.noaa.rst.
Creating file docs/api/task_geo.data_sources.noaa.api_connector.rst.
Creating file docs/api/task_geo.data_sources.noaa.api_formatter.rst.
Creating file docs/api/task_geo.data_sources.noaa.ftp_connector.rst.
Creating file docs/api/task_geo.data_sources.noaa.references.rst.
/Library/Developer/CommandLineTools/usr/bin/make -C docs html
Running Sphinx v2.2.0

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/opt/anaconda3/lib/python3.7/site-packages/sphinx/config.py", line 361, in eval_config_file
    execfile_(filename, namespace)
  File "/opt/anaconda3/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 81, in execfile_
    exec(code, _globals)
  File "/Users/../CoronaWhy/task-geo/docs/conf.py", line 23, in <module>
    import task_geo
ModuleNotFoundError: No module named 'task_geo'

make[1]: *** [html] Error 2
make: *** [docs] Error 2

[ManuelAlvarezC]

Furthermore @awalther got the following issue while trying to replicate the error:

# OS: OS X High Sierra 10.13.4
# Python version: 3.7.0 (CPython)
# Docutils version: 0.16 release
# Jinja2 version: 2.11.1
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "/Users/alexwalther/.pyenv/versions/task_geo/lib/python3.7/site-packages/sphinx/cmd/build.py", line 279, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/Users/alexwalther/.pyenv/versions/task_geo/lib/python3.7/site-packages/sphinx/application.py", line 244, in __init__
    self.setup_extension(extension)
  File "/Users/alexwalther/.pyenv/versions/task_geo/lib/python3.7/site-packages/sphinx/application.py", line 398, in setup_extension
    self.registry.load_extension(self, extname)
  File "/Users/alexwalther/.pyenv/versions/task_geo/lib/python3.7/site-packages/sphinx/registry.py", line 414, in load_extension
    metadata = setup(app)
  File "/Users/alexwalther/.pyenv/versions/task_geo/lib/python3.7/site-packages/m2r.py", line 652, in setup
    app.add_source_parser('.md', M2RParser)
  File "/Users/alexwalther/.pyenv/versions/task_geo/lib/python3.7/site-packages/sphinx/application.py", line 1069, in add_source_parser
    self.registry.add_source_parser(*args, **kwargs)
TypeError: add_source_parser() takes 2 positional arguments but 3 were given```

[ManuelAlvarezC]

For the moment, we will do the following:

@cryptox31:
Please provide your OS, python version and commit SHA.

@awalther:
Please, provide your commit SHA.

Both:
Let me explain what is going on. There are two issues here:

1. There may be an error on the Makefile for macOS.
2. The latest release of sphinx version (3.0.0) ( the package that build the docs) breaks the building of docs for some additional packages we are using.

We are gonna solve by:

1. You will give the information I requested at the beginning of my document. After making sure we are checking the same, or comparable OS, python and commits.
2. We will add a ', <3' at the end of the sphinx requirement in setup.py, both of you, locally, without opening a PR.And check if this solves or not the build. If that solves the issue on both of you, then this is the solution.
3. If this still crashes, we will see the tracebacks and see how to proceed.

Any doubts, please write them below

[ManuelAlvarezC]

After #48 is merged, could you check again?

[ilovechai]

@ManuelAlvarezC

MacOs Catalina 10.15.4
Python 3.7.6
Commit SHA c4af4d7

Please change this https://github.com/CoronaWhy/task-geo/blob/master/Makefile#L105 in your current makefile to https://github.com/cryptox31/task-geo/blob/17002698dbc7ef2dfaea589fb904c92b034b3918/Makefile#L100
to fix

find . -name '*.egg' -exec rm -f {} +
rm: ./venv/lib/python3.7/site-packages/pip-19.0.3-py3.7.egg: is a directory

[ManuelAlvarezC]

I will do it.
There is another thing that is not documented, you need to install the system dependency pandocin order to build the docs locally, in linux you can do so with:

sudo apt install pandoc

MacOs users will need to run

brew install pandoc

Windows users should run:

choco install pandoc