Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Regressive Web Documentation #1374

Open
RobertFlatt opened this issue Nov 9, 2021 · 7 comments
Open

Regressive Web Documentation #1374

RobertFlatt opened this issue Nov 9, 2021 · 7 comments

Comments

@RobertFlatt
Copy link
Contributor

Description

The Kivy documentation on the web https://kivy.org/doc/stable/ has lost the documentation for Kivy 2.0.0 . It is only up to Kivy 1.11.1

This is a particular problem for Buildozer as the install documentation on the Web is incorrect. https://kivy.org/doc/stable/guide/packaging-android.html#packaging-android

For potential user reading this, the correct install documentation is https://github.com/kivy/buildozer/blob/master/docs/source/installation.rst

This regressive behavior gives rise to a truly terrible new user experience. Documentation with an implicit "ignore the parts that are wrong" is unsupportable.

@tshirtman tshirtman transferred this issue from kivy/buildozer Nov 9, 2021
@tshirtman tshirtman transferred this issue from kivy/kivy Nov 9, 2021
@tshirtman
Copy link
Member

tshirtman commented Nov 9, 2021

(sorry went a bit fast in transfering it, my bad)

But the fact that the doc was lost looks like a kivy issue first.
No time to investigate now, but seems like we have to check what's happening to it as a priority.

@RobertFlatt
Copy link
Contributor Author

Thanks, I'd suspect a Kivy issue too. Strangely the Kivy install instruction are for 2.0.0 (uses [base] etc), even if if says 1.11.1 in the top left. I posted here because Buildozer install instruction are old ones. Not clear to me I know how to check the extent of the issue.

@RobertFlatt
Copy link
Contributor Author

This KivyMD script also implements the old install instructions https://github.com/HeaTTheatR/KivyMD-data/blob/master/install-kivy-buildozer-dependencies.sh

@tshirtman
Copy link
Member

Actually, i understood the other day, though its' really not obvious, but stable actually is 2.0.0, so nothing is missing.

Now the issue is that the instructions for buildozer are obsolete in this version, so a fix to these in the stable branch on github would be needed.

@RobertFlatt
Copy link
Contributor Author

It looks like that is not exactly the issue because:

Buildozer has no branch or tag labeled 'stable' on github.

Buildozer does have a 'master' branch github, but for Buildozer install docs the 'master' on 'kivy.org' does not match the 'master' on github.

My original comment was too general, but the issue in publishing the documentation is real. Where is the documentation on publishing the documentation?

@tshirtman
Copy link
Member

tshirtman commented Nov 16, 2021

Hm, so maybe kivy docs shouldn't try to tell how to install buildozer, but instead point to the buildozer docs, to avoid falling out of sync?

Documentation is published automatically, for kivy through our own system, that is partially documented here https://github.com/kivy/kivy-website-docs. For buildozer and others simply using readthedocs, but it seems not to be automatic, would be nice to configure web hooks, i just pushed the button for buildozer, but it failed, apparently trying to build with python2.7x

git clone --no-single-branch --depth 50 https://github.com/kivy/buildozer .
git checkout --force origin/master
git clean -d -f -f
python2.7 -mvirtualenv /home/docs/checkouts/readthedocs.org/user_builds/buildozer/envs/latest
/home/docs/checkouts/readthedocs.org/user_builds/buildozer/envs/latest/bin/python -m pip install --upgrade --no-cache-dir pip setuptools
/home/docs/checkouts/readthedocs.org/user_builds/buildozer/envs/latest/bin/python -m pip install --upgrade --no-cache-dir mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<2.2
cat docs/source/conf.py
/home/docs/checkouts/readthedocs.org/user_builds/buildozer/envs/latest/bin/python -m sphinx -T -b html -d _build/doctrees -D language=en . _build/html
/home/docs/checkouts/readthedocs.org/user_builds/buildozer/envs/latest/bin/python -m sphinx -T -b readthedocssinglehtmllocalmedia -d _build/doctrees -D language=en . _build/localmedia
/home/docs/checkouts/readthedocs.org/user_builds/buildozer/envs/latest/bin/python -m sphinx -b latex -D language=en -d _build/doctrees . _build/latex
Running Sphinx v1.8.5
loading translations [en]... done
making output directory...
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [latex]: all documents
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing Buildozer.tex...
Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/buildozer/envs/latest/lib/python2.7/site-packages/sphinx/builders/latex/__init__.py", line 201, in write
    if toctrees[0].get('maxdepth') > 0:
TypeError: 'generator' object has no attribute '__getitem__'
The full traceback has been saved in /tmp/sphinx-err-Tvxo8A.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks! 

@RobertFlatt
Copy link
Contributor Author

Hm, so maybe kivy docs shouldn't try to tell how to install buildozer, but instead point to the buildozer docs, to avoid falling out of sync?

I'd say do whatever is easiest.

Interesting to note that the Readthedocs entry is correct for install Buildozer 1.2 (the current). And their build history is informative https://readthedocs.org/projects/buildozer/builds/

partially documented

I laughed out loud.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants