sphinx build errors #696
sphinx build errors #696
Conversation
| deps = | ||
| sqlalchemy | ||
| Sphinx | ||
| sphinx_rtd_theme | ||
| changedir = doc | ||
| commands = /usr/bin/make {posargs} | ||
| commands = /usr/bin/make SPHINXOPTS='-W' {posargs} |
|
Looks awesome! Except
|
|
@erikbern changes squash for 2. regarding 1. I've added a note. |
|
I don't think we need to syntax check README.rst since you can look at it by just going to the branch on Github. Can we just avoid checking it? |
|
@steenzout Maybe add a copy command in [docs] to copy README.rst to doc before docs being run? :) No duplication, everybody is happy. |
|
+1 |
|
@themalkolm if I copy it, sphinx will try to validate it when doing HTML docs generation just like when it was pointing to the ../README.rst. :) I can add a command to copy it then and perform a cleanup but next time some adds something to the main README.rst it may break the docs generation. give me 1h... |
|
I would say it is OK to break documentation if README.rst is broken. |
|
Maybe adding [docs] to default targets to tox would ensure docs are never borked. |
|
This commit message is unreadable since the header does not describe the overall change. The imporpant change of this patch set is not that you ignore E308. |
|
@Tarrasch I've changed the 1st line of the commit message. @themalkolm I've merged the docsapi tox env with the docs tox env since it didn't made any sense to have it separated (I didn't realize that you had to build the docs in 2 steps: api and then HTML). to sync the README.rst I copy the file over, change github URL to local file references and remove the badges using sed commands. if you really want the badges on the docs (?) we'd have to copy the badges every time we try to generate the documentation and be sure you're picking up the badge for the right branch / tag. |
|
Great! Maybe just squash everything since the first commit is already a monster-commit |
|
squash done. |
| sphinx-apidoc -o doc/api -T luigi | ||
|
|
||
| # sync README.rst file | ||
| cp README.rst doc/README.rst |
There was a problem hiding this comment.
Can you delete doc/readme.rst since you're copying README.rst into doc/README.rst now?
Also Sphinx is throwing some errors. Could it be because you need to copy README.rst into doc/readme.rst (lower case) rather than doc/README.rst?
Warning, treated as error: /home/travis/build/spotify/luigi/doc/readme.rst:: WARNING: document isn't included in any toctree
ignore autopep8 E309 since if class has docstring, it will be separated by blank line. changed sqlalchemy import statements. this is necessary to fix bug in sphinx-doc issue#1530: sphinx-doc/sphinx#1530 fixed luigi.interface.Interface.run sphinx complaints. improved luigi.interface.run docstring. fixed luigi.lock.getpcmd sphinx complaints. fixed luigi.contrib.mysqldb.MySqlTarget docstring complaints and made 1st character of parameter description lowercase. fixed luigi.contrib.redshift.RedshiftManifestTask sphinx complaints. fixed sphinx SEVERE: Title level inconsistent. fixed sphinx "ERROR: Unknown target name" errors. fixed sphinx "WARNING: Explicit markup ends without a blank line" errors. fixed sphinx "WARNING: Explicit markup ends without a blank line" errors. fixed sphinx "Duplicate explicit target name: 'spotify'" error. fixed broken URL to Yarn REST API. fixed URL to oozie. fixed URL for luigi-user Google group. fixed URL to spotify. changed URL to source code to make sphinx linkcheck pass. added new readme.rst to exclude_pattern to fix sphinx complaint that it's not part of a table of content. removed the html_static_path to fix sphinx build issue. sphinx warnings now make the build break. added docs-test tox environment to the travis build. problems with documentation will now make the build break. added more rules to .gitignore based on gitignore.io: Python, vim, OSX, Vagrant, PyCharm. fixed sphinx warning to include luigi.tools. merge tox docsapi with tox docs. tox docsapi environment creates new files that might break the documentation generation so moved the command into the tox docs environment. synchronize README.rst in github and readthedocs. copy of README.rst to doc directory. URLs pointing to github changed to point to local files. badges removed from the doc/README.rst. added comments to build doc commands. whitelist cp and sed commands. README.rst added to sphinx exclude_patterns. this will bypasses the warning sphinx gives due to the fact that README.rst is not part of a table of contents.
|
@erikbern I saw that. sorry about the extra spam! |
|
awesome! |
|
this was commit #1,500 :) |
|
:) |
Hello,
this PR is to make sphinx doc generation warnings and link check break the build if something gets changed on the docs that isn't right.
I had to:
change the import for sqlalchemy in the
luigi/db_task_history.pyso that sphinx wouldn't complain (hope it doesn't look that ugly!)fix all the warnings on the docstrings
fix URLs so that permanent redirects don't throw sphinx errors anymore
had to make a copy of the README.rst into
doc/readme.rstsince links to external images / figures will throw a sphinx warning during the documentation build (is this ok? at least, for now?)2 minor sphinx configuration tweaks to fix / bypass / overcome sphinx warnings
added docs-test tox environment
added docs-test tox environment to the travis build
I also added a few changes to the .gitignore.
Based on the content you previously had I:
generated new rules on gitignore.io and added them.
removed what became duplicate from the top of the file
ordered the project custom rules by alphabetical order
added a few python files that show up after I run the tests
let me know if you want me to rebase all of this into 1 commit (some projects don't like a series of commits).
comments welcomed!...
cheers