#528 closed defect (fixed)
Add a documentation generator that creates a PDF or HTML files locally
Reported by: | anonymous | Owned by: | Harkins |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | trivial | Keywords: | doc-refactor |
Cc: | Triage Stage: | Accepted | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
It would be nice to have doc generation script for making pdf or static html at local computer after each svn update.
Attachments (3)
Change History (31)
comment:1 by , 19 years ago
Summary: | docs generator → Add a documentation generator that creates a PDF or HTML files locally |
---|
follow-up: 18 comment:2 by , 19 years ago
priority: | normal → lowest |
---|---|
Severity: | normal → trivial |
comment:3 by , 18 years ago
Triage Stage: | Unreviewed → Design decision needed |
---|
comment:4 by , 18 years ago
Triage Stage: | Design decision needed → Accepted |
---|
comment:5 by , 17 years ago
Maybe the first needed thing is to have http://www.djangoproject.com/documentation/ as a .rst file in SVN (index.rst ?) it's currently a hardcoded template ([source:djangoproject.com/django_website/templates/docs/index.html]). Could the index page be moved to an .rst?
comment:6 by , 17 years ago
#1527 has been marked as a duplicate of this ticket. That one provides a Makefile that calls rst2html.py for every file in docs/ in case you want it ;)
comment:8 by , 17 years ago
FYI: I've just done a similar thing for my own projects (some of this information might be useful to you). I'm using MoinMoin as my wiki and it has a plugin for PDF creation that uses htmldoc as the pdf generator. It provides a really nice interface and works like a dream.
I wrote a small python script in my build system that simply got the web pages with the 'CreatePdf' action (ie after calling the wiki macro to create a PDF) and wrote it to a file which I zip up into my release.
The macro (and info) is here: http://moinmo.in/ActionMarket/PdfAction
Hope this helps :) - Tushar.
comment:9 by , 17 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:10 by , 17 years ago
Has patch: | set |
---|
The script I've created does not produce especially beautiful output, but the basic basic functionality is there to render the Django doc dir into one large HTML doc or many small HTML docs with an index.
comment:11 by , 17 years ago
Keywords: | sprintsept14 added |
---|
comment:13 by , 17 years ago
Cc: | added |
---|
comment:14 by , 17 years ago
Triage Stage: | Accepted → Ready for checkin |
---|
+1
if you want to improve the documenation, you need some way to check
the wiki syntax before you create a patch.
the patch render_docs.py.diff works for me. It think it is ready for check in (it can't break anything).
follow-up: 19 comment:15 by , 17 years ago
Needs documentation: | set |
---|---|
Patch needs improvement: | set |
Triage Stage: | Ready for checkin → Accepted |
This isn't ready to check in.
- There should be practically no executable code at the top level. In other words, importing the file should not execute it. At least a
main()
function andif __name__ == '__main__':
guard are required. - The imports should conform to PEP 8 style guidelines.
- If you don't have docutils installed (which will be noticable in the import section), a helpful error message would be good, since docutils don't come by default with Python.
If somebody wants to take this further, it's probably worth checking in with Adrian (see comment 7) to find out where he's up.
by , 17 years ago
Attachment: | render_docs.py.2.diff added |
---|
comment:16 by , 17 years ago
Needs documentation: | unset |
---|---|
Patch needs improvement: | unset |
I wrote a small bit of documentation and did the requested things for improving the patch.
comment:17 by , 17 years ago
Apparently #6443 was created to suggest pisa from http://www.htmltopdf.org/ for conversion from HTML to PDF. I've closed it as duplicate of this and added the relevant info here.
comment:18 by , 17 years ago
Component: | Documentation → Template system |
---|---|
Needs documentation: | set |
Needs tests: | set |
Patch needs improvement: | set |
Resolution: | → worksforme |
Status: | assigned → closed |
Triage Stage: | Accepted → Unreviewed |
Version: | → 0.95 |
Replying to adrian:
comment:19 by , 17 years ago
Version: | 0.95 → other branch |
---|
Replying to mtredinnick:
This isn't ready to check in.
- There should be practically no executable code at the top level. In other words, importing the file should not execute it. At least a
main()
function andif __name__ == '__main__':
guard are required.- The imports should conform to PEP 8 style guidelines.
- If you don't have docutils installed (which will be noticable in the import section), a helpful error message would be good, since docutils don't come by default with Python.
If somebody wants to take this further, it's probably worth checking in with Adrian (see comment 7) to find out where he's up.
comment:20 by , 17 years ago
Component: | Template system → Documentation |
---|---|
Needs documentation: | unset |
Needs tests: | unset |
Resolution: | worksforme |
Status: | closed → reopened |
Triage Stage: | Unreviewed → Accepted |
Version: | other branch → SVN |
This ain't a toy, sparky.
comment:21 by , 17 years ago
I've created a somewhat more extended version of this that produces output that looks very similar to real Django documentation. See DjangoSpecifications/Docs/ConvertingRestToOtherFormats for overview, screenshots and patch.
comment:22 by , 17 years ago
Keywords: | sprintpycon08 added |
---|---|
Patch needs improvement: | unset |
Triage Stage: | Accepted → Ready for checkin |
comment:23 by , 17 years ago
Triage Stage: | Ready for checkin → Accepted |
---|
Not ready-for-checkin, since there doesn't appear to be any single patch to checkin, it's a large change if it's the thing you've posted to that above URL, so needs careful review by somebody other than yourself, plus, as Jacob mentioned, he's also working on a toolchain, so he'll possibly want to take bits and pieces of both approaches.
comment:24 by , 17 years ago
Posting the final patch attached to the wiki page here as well to avoid confusion (re: there doesn't appear to be any single patch to checkin).
by , 17 years ago
Attachment: | build_htmldocs-links_work-with_docs.diff added |
---|
Patch that implements a management command for adding docs, with documentation.
comment:25 by , 16 years ago
Keywords: | doc-refactor added; sprintsept14 sprintpycon08 removed |
---|---|
milestone: | → 1.0 beta |
An alternative system using Sphinx will be implemented during the documentation refactor effort.
Marking 1.0 beta as the documentation refactor effort should land in that milestone if at all.
comment:26 by , 16 years ago
Resolution: | → fixed |
---|---|
Status: | reopened → closed |
We've had a Sphinx builder for quite some time now -- since [7370].
comment:27 by , 16 years ago
Cc: | removed |
---|
This would be nice to have. A very low-priority enhancement.