search

ColoradoSchoolOfMines / mozzarella

Mozzarella is a web application made to help student computing clubs better collaborate and organize their projects, presentations, and even mailing list messages.
https://acm.mines.edu
GNU General Public License v3.0
7 stars 3 forks source link

docs building errors #86

Closed jackrosenthal closed 6 years ago

jackrosenthal commented 6 years ago

see cleanup comment on #85

edwargix commented 6 years ago

Will fix asap

edwargix commented 6 years ago

When Sphinx uses autodoc to import docs from Python code, it evaluates entire modules. Thus, the following errors

WARNING: error while formatting arguments for acmwebsite.controllers.mailinglist.MailingListController.subscribe: 
WARNING: error while formatting arguments for acmwebsite.controllers.root.RootController.login: 
WARNING: error while formatting arguments for acmwebsite.controllers.root.RootController.post_login: 
WARNING: error while formatting arguments for acmwebsite.controllers.root.RootController.post_logout:

arise from the fact that the functions have an optional argument that defaults to the value tg.lurl(str), and this value can't easily be determined without running the entire application. There doesn't seems to be a way to prevent Sphinx from evaluating function arguments, so the only solution I can come up with is to manually write the function signatures for each of these functions in the docstring itself. This is what commit 8e154456f8bfc2fc0c1f598e5422a9efff4e7a4b does. I have no idea what these errors

/home/jrosenth/Dropbox/acm/acm-website/acmwebsite/lib/card.py:docstring of acmwebsite.lib.card.CardTypes.generate_cards:11: WARNING: Unexpected indentation.
/home/jrosenth/Dropbox/acm/acm-website/acmwebsite/lib/card.py:docstring of acmwebsite.lib.card.CardTypes.generate_cards:15: WARNING: Unexpected indentation.

come from as the lines of code it references, card.py:11 and card.py:15, look fine. Thankfully these warnings don't affect the generated documentation.

edwargix commented 6 years ago

The final warnings

/home/jrosenth/Dropbox/acm/acm-website/docs/modules.rst:4: WARNING: toctree contains reference to nonexisting document 'acmwebsite'
/home/jrosenth/Dropbox/acm/acm-website/docs/modules.rst: WARNING: document isn't included in any toctree

arise because modules.rst is never used and refers to a non-existent file. For now, commit 104fd0e3482aaab508d4c767a102967cb4bc3546 will delete it and we can resurrect it later when writing the real documentation.