freetype/docwriter

API documentation generator of the FreeType library.

docwriter's Issues

refdoc build fails

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

Contribution file required

The repository needs a contribution file so that it is easy for newcomers to dive in.

Static site assets not included with docwriter.

Description

The assets for static site are not included with the docwriter package, and are currently in the docs/reference/markdown directory in the freetype2 repository.

Expected behavior

Docwriter should ship with these assets so that they can be easily modified.

Style guide issue

Incompatible dependency of Markdown between mkdocs-material and mkdocs.

This is because mkdocs-material changed its requirements to Markdown<3.2 in squidfunk/mkdocs-material@bbba04a (included in release 4.6.0) due to a breaking change in Python-markdown (see Python-Markdown/markdown#862), and has been fixed since.

Docwriter cannot directly bump the required versions, because this also affects code blocks that docwriter inserts in markdown files. These issues need to be addressed in a minor release.

Consider using Readme as the long description

See https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py

[...]
with open("README.md", "r") as fh:
    long_description = fh.read()
[...]
    long_description=long_description,
    long_description_content_type="text/markdown",

This will make the Readme render on https://pypi.org/project/docwriter/. Compare with e.g. https://pypi.org/project/black/.

Travis CI with FreeType's version

Cool, mirroring the repo seems to work well 😃 Just a short note: I think that the build results of FreeType's Travis account (not @nikramakrishnan) should be linked in the README.

No index.html in generated site.

Generated static website does not have an 'index.html' page which makes it confusing for anyone browsing the docs.

Discussed at http://lists.nongnu.org/archive/html/freetype-devel/2018-08/msg00000.html.

Consider using setuptools_scm

It will automatically derive the package version from Git tags.

https://github.com/pypa/setuptools_scm#setuppy-usage

Making a new release becomes as easy as tagging the commit you want to release, no more tedious version updates. This funnily enough encouraged me to release more often.

Dependabot couldn't authenticate with https://pypi.python.org/simple/

Dependabot couldn't authenticate with https://pypi.python.org/simple/.

You can provide authentication details in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'.

View the update logs.