Code

Opened 9 years ago

Closed 6 years ago

Last modified 3 years ago

#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: master
Severity: trivial Keywords: doc-refactor
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

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)

render_docs.py.diff (2.2 KB) - added by Harkins 7 years ago.
Patch: a script to render HTML docs
render_docs.py.2.diff (3.2 KB) - added by programmerq 6 years ago.
build_htmldocs-links_work-with_docs.diff (22.1 KB) - added by mrts 6 years ago.
Patch that implements a management command for adding docs, with documentation.

Download all attachments as: .zip

Change History (31)

comment:1 Changed 9 years ago by adrian

  • Summary changed from docs generator to Add a documentation generator that creates a PDF or HTML files locally

comment:2 follow-up: Changed 8 years ago by adrian

  • priority changed from normal to lowest
  • Severity changed from normal to trivial

comment:3 Changed 7 years ago by SmileyChris

  • Triage Stage changed from Unreviewed to Design decision needed

comment:4 Changed 7 years ago by mtredinnick

  • Triage Stage changed from Design decision needed to Accepted

This would be nice to have. A very low-priority enhancement.

comment:5 Changed 7 years ago by Marc Fargas <telenieko@…>

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 Changed 7 years ago by Marc Fargas <telenieko@…>

#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:7 Changed 7 years ago by adrian

I've started working on this in my spare time.

comment:8 Changed 7 years ago by anonymous

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 Changed 7 years ago by Harkins

  • Owner changed from nobody to Harkins
  • Status changed from new to assigned

Claiming #528 and #4940 for Sprint14Sep.

Changed 7 years ago by Harkins

Patch: a script to render HTML docs

comment:10 Changed 7 years ago by Harkins

  • 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 Changed 7 years ago by Harkins

  • Keywords sprintsept14 added

comment:12 Changed 7 years ago by ubernostrum

Marked #4940 as a duplicate.

comment:13 Changed 7 years ago by Thomas Güttler <hv@…>

  • Cc hv@… added

comment:14 Changed 7 years ago by Thomas Güttler <hv@…>

  • Triage Stage changed from Accepted to 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).

comment:15 follow-up: Changed 7 years ago by mtredinnick

  • Needs documentation set
  • Patch needs improvement set
  • Triage Stage changed from Ready for checkin to 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 and if __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.

Changed 6 years ago by programmerq

comment:16 Changed 6 years ago by programmerq

  • 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 Changed 6 years ago by ramiro

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 in reply to: ↑ 2 Changed 6 years ago by anonymous

  • Component changed from Documentation to Template system
  • Needs documentation set
  • Needs tests set
  • Patch needs improvement set
  • Resolution set to worksforme
  • Status changed from assigned to closed
  • Triage Stage changed from Accepted to Unreviewed
  • Version set to 0.95

Replying to adrian:

comment:19 in reply to: ↑ 15 Changed 6 years ago by anonymous

  • Version changed from 0.95 to 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 and if __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 Changed 6 years ago by Simon Greenhill <dev@…>

  • Component changed from Template system to Documentation
  • Needs documentation unset
  • Needs tests unset
  • Resolution worksforme deleted
  • Status changed from closed to reopened
  • Triage Stage changed from Unreviewed to Accepted
  • Version changed from other branch to SVN

This ain't a toy, sparky.

comment:21 Changed 6 years ago by mrts

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 Changed 6 years ago by mrts

  • Keywords sprintsept14, sprintpycon08 added; sprintsept14 removed
  • Patch needs improvement unset
  • Triage Stage changed from Accepted to Ready for checkin

comment:23 Changed 6 years ago by mtredinnick

  • Triage Stage changed from Ready for checkin to 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 Changed 6 years ago by mrts

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).

Changed 6 years ago by mrts

Patch that implements a management command for adding docs, with documentation.

comment:25 Changed 6 years ago by mrts

  • Keywords doc-refactor added; sprintsept14, sprintpycon08 removed
  • milestone set to 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 Changed 6 years ago by jacob

  • Resolution set to fixed
  • Status changed from reopened to closed

We've had a Sphinx builder for quite some time now -- since [7370].

comment:27 Changed 6 years ago by guettli

  • Cc hv@… removed

comment:28 Changed 3 years ago by jacob

  • milestone 1.0 beta deleted

Milestone 1.0 beta deleted

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.