refdoc build fails

[heftig]

Recently, make refdoc-venv on FreeType master started failing:

Setting up virtualenv for Python...
virtualenv --python=python3 /build/freetype2-git/src/freetype2/docs/env
created virtual environment CPython3.8.6.final.0-64 in 349ms
  creator CPython3Posix(dest=/build/freetype2-git/src/freetype2/docs/env, clear=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/build/.local/share/virtualenv)
    added seed packages: pip==20.2.3, setuptools==50.3.1, wheel==0.35.1
  activators BashActivator,CShellActivator,FishActivator,PowerShellActivator,PythonActivator,XonshActivator
Installing docwriter...
/build/freetype2-git/src/freetype2/docs/env/bin/python3 -m pip install docwriter
Collecting docwriter
  Downloading docwriter-1.3-py3-none-any.whl (27 kB)
Collecting PyYAML==5.3.1
  Downloading PyYAML-5.3.1.tar.gz (269 kB)
Collecting mistune==0.8.4
  Downloading mistune-0.8.4-py2.py3-none-any.whl (16 kB)
Collecting mkdocs-material==4.6.3
  Downloading mkdocs_material-4.6.3-py2.py3-none-any.whl (723 kB)
Collecting mkdocs==1.1
  Downloading mkdocs-1.1-py2.py3-none-any.whl (6.4 MB)
Collecting markdown>=3.2
  Downloading Markdown-3.3.3-py3-none-any.whl (96 kB)
Collecting pymdown-extensions>=6.3
  Downloading pymdown_extensions-8.0.1-py2.py3-none-any.whl (206 kB)
Collecting Pygments>=2.4
  Downloading Pygments-2.7.2-py3-none-any.whl (948 kB)
Collecting lunr[languages]==0.5.6
  Downloading lunr-0.5.6-py2.py3-none-any.whl (36 kB)
Collecting click>=3.3
  Downloading click-7.1.2-py2.py3-none-any.whl (82 kB)
Collecting Jinja2>=2.10.1
  Downloading Jinja2-2.11.2-py2.py3-none-any.whl (125 kB)
Collecting livereload>=2.5.1
  Downloading livereload-2.6.3.tar.gz (25 kB)
Collecting tornado>=5.0
  Downloading tornado-6.1-cp38-cp38-manylinux2010_x86_64.whl (427 kB)
Collecting future>=0.16.0
  Downloading future-0.18.2.tar.gz (829 kB)
Collecting six>=1.11.0
  Downloading six-1.15.0-py2.py3-none-any.whl (10 kB)
Collecting nltk>=3.2.5; extra == "languages"
  Downloading nltk-3.5.zip (1.4 MB)
Collecting MarkupSafe>=0.23
  Downloading MarkupSafe-1.1.1-cp38-cp38-manylinux1_x86_64.whl (32 kB)
Collecting joblib
  Downloading joblib-0.17.0-py3-none-any.whl (301 kB)
Collecting regex
  Downloading regex-2020.10.28-cp38-cp38-manylinux2014_x86_64.whl (736 kB)
Collecting tqdm
  Downloading tqdm-4.51.0-py2.py3-none-any.whl (70 kB)
Building wheels for collected packages: PyYAML, livereload, future, nltk
  Building wheel for PyYAML (setup.py): started
  Building wheel for PyYAML (setup.py): finished with status 'done'
  Created wheel for PyYAML: filename=PyYAML-5.3.1-cp38-cp38-linux_x86_64.whl size=44619 sha256=061ea858ce3e7d8bfb7721a527bcbfacbb329d3a789d80ae1588cc4e2c99ad6d
  Stored in directory: /build/.cache/pip/wheels/13/90/db/290ab3a34f2ef0b5a0f89235dc2d40fea83e77de84ed2dc05c
  Building wheel for livereload (setup.py): started
  Building wheel for livereload (setup.py): finished with status 'done'
  Created wheel for livereload: filename=livereload-2.6.3-py2.py3-none-any.whl size=24713 sha256=fc60b72e349f5d6ac8c4250fa2457a989b67cdc4f32b3f243b68e2e9e0fdcaff
  Stored in directory: /build/.cache/pip/wheels/48/d7/34/372e0521bd5c9f6dcdff307e37ef6f9c00c1e1e2afc9707b5c
  Building wheel for future (setup.py): started
  Building wheel for future (setup.py): finished with status 'done'
  Created wheel for future: filename=future-0.18.2-py3-none-any.whl size=491059 sha256=eed951c464ed67cc799a95343825709a9557e3ce21452f32476d99073ab37fa2
  Stored in directory: /build/.cache/pip/wheels/8e/70/28/3d6ccd6e315f65f245da085482a2e1c7d14b90b30f239e2cf4
  Building wheel for nltk (setup.py): started
  Building wheel for nltk (setup.py): finished with status 'done'
  Created wheel for nltk: filename=nltk-3.5-py3-none-any.whl size=1434678 sha256=b7edf11d64594a242ee0b8b6b965f714be86970e1bc7e1635b9aaa17ee81c113
  Stored in directory: /build/.cache/pip/wheels/ff/d5/7b/f1fb4e1e1603b2f01c2424dd60fbcc50c12ef918bafc44b155
Successfully built PyYAML livereload future nltk
Installing collected packages: PyYAML, mistune, markdown, pymdown-extensions, Pygments, future, six, click, joblib, regex, tqdm, nltk, lunr, MarkupSafe, Jinja2, tornado, livereload, mkdocs, mkdocs-material, docwriter
Successfully installed Jinja2-2.11.2 MarkupSafe-1.1.1 PyYAML-5.3.1 Pygments-2.7.2 click-7.1.2 docwriter-1.3 future-0.18.2 joblib-0.17.0 livereload-2.6.3 lunr-0.5.6 markdown-3.3.3 mistune-0.8.4 mkdocs-1.1 mkdocs-material-4.6.3 nltk-3.5 pymdown-extensions-8.0.1 regex-2020.10.28 six-1.15.0 tornado-6.1 tqdm-4.51.0
WARNING: You are using pip version 20.2.3; however, version 20.2.4 is available.
You should consider upgrading via the '/build/freetype2-git/src/freetype2/docs/env/bin/python3 -m pip install --upgrade pip' command.
Running docwriter...
/build/freetype2-git/src/freetype2/docs/env/bin/python3 -m docwriter \
                      --prefix=ft2 \
                      --title=FreeType-.. \
                      --site=reference \
                      --output=/build/freetype2-git/src/freetype2/docs \
                      /build/freetype2-git/src/freetype2/include/freetype/*.h \
                      /build/freetype2-git/src/freetype2/include/freetype/config/*.h \
                      /build/freetype2-git/src/freetype2/include/freetype/cache/*.h
INFO    -  Cleaning output directory
INFO    -  Building markdown documentation to directory: /build/freetype2-git/src/freetype2/docs/markdown
WARNING -  Undefined cross reference 'FTC_Property_Set'.
WARNING -  Undefined cross reference 'FTC_Property_Get'.
Traceback (most recent call last):
  File "/usr/lib/python3.8/runpy.py", line 194, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.8/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "/build/freetype2-git/src/freetype2/docs/env/lib/python3.8/site-packages/docwriter/__main__.py", line 169, in <module>
    main()
  File "/build/freetype2-git/src/freetype2/docs/env/lib/python3.8/site-packages/docwriter/__main__.py", line 164, in main
    formatter.section_dump_all()
  File "/build/freetype2-git/src/freetype2/docs/env/lib/python3.8/site-packages/docwriter/tomarkdown.py", line 631, in section_dump_all
    self.section_dump( section,
  File "/build/freetype2-git/src/freetype2/docs/env/lib/python3.8/site-packages/docwriter/formatter.py", line 191, in section_dump
    self.section_enter( section )
  File "/build/freetype2-git/src/freetype2/docs/env/lib/python3.8/site-packages/docwriter/tomarkdown.py", line 571, in section_enter
    print( self.make_md_items( section.description ) )
  File "/build/freetype2-git/src/freetype2/docs/env/lib/python3.8/site-packages/docwriter/tomarkdown.py", line 302, in make_md_items
    for item in items:
TypeError: 'NoneType' object is not iterable
make: *** [/build/freetype2-git/src/freetype2/builds/freetype.mk:320: refdoc-venv] Error 1

[heftig]

Replacing return None with return [] in DocBlock.get_markup_items seems to fix this.

[heftig]

The cause in the FreeType repo is an empty line after the * @description: line.