The documentation needs serious refinement

[kytta]

Problem

So, I have been working on a project where I had to use xhtml2pdf, so naturally, I was using the docs.

Now, I really don't want to offend anyone, but the current docs are not good. The navigation is very confusing, finding information takes significant amounts of time, and some stuff isn't even included in the docs (I had to dig through the source code to discover -pdf-word-wrap).

Some places of the "Reference" have XXX in them, and it's been this way for ages. The text can be unclear and creates more questions than answers.

I am willing to help, and I am ready to refine the documentation myself. All I need is help from the maintainers (since I might have some questions about what the code does) and an approval to basically make lots of changes in the docs, possibly creating a huge PR.

Let me know what you think about it. This project has a huge potential (being AFAIK the only HTML-to-PDF library that doesn't require extraneous dependencies) and it's a shame that the docs aren't clear enough :(

Proposed structure

• Homepage - here a small except from README about the project
  • Getting started - I suggest uniting Installation (without dev docs) and Usage into one "quick start"-esque page.
    • Installation
    • Usage in Python scripts
    • Usage in Django apps
    • Usage as a command line tool
      • Advanced CLI usage
  • User Guide — here the main usage guide; more advanced than the previous chapter
    • PDF vs. HTML
    • Defining Page Layout
      • Managing multiple Page Templates
    • Working with Frames
      • Static Frames
      • Content Frames
      • Control page splits
    • Page Elements
      • Header and Footer
        • Page numbers
      • Table of Contents
        • Change outline levels
      • Tables
      • Images
      • Barcodes
    • Using fonts
      • Pre-installed fonts
      • Custom fonts
      • CJK font support
      • Right-to-Left languages
    • CSS Styling — supported properties
    • Outputting the PDF
  • API Reference — purely technical reference
    • HTML API — here the information about supported HTML tags
    • Python API — here the information about Python classes and methods
  • Contributing — here some information about working on xhtml2pdf
    • Contributing guide / CoC — there is no separate guide and/or code of conduct; perhaps adding them wouldn't be too bad
    • Development environment
    • Running tests
  • Release Notes

[fbernhart]

@NickKaramoff I support this 100%!

I also had to work with xhtml2pdf in the past and I really liked it. As I also wanted to start contributing to an open source project, I started improving xhtml2pdf bit by bit in the last few weeks.

Improving the docs is as well on my to-do list, but I haven't had time for it yet.

So I would be very grateful, if you would help improving the documentation. I'm 100% your opinion, that the documentation is pretty bad structured, misses a lot of things and needs a serious renewal.

I'm not the maintainer nor do I fully understand all of the code yet. But if there's anything I could help you with, let me know. 😊

[luisza]

Hi, I agree with you documentation is very important and this project has a ugly documentation.
I am the main maintainer, but I don't code most part of the code (I just check and approved PR, and code a little features).
But I am available for help you and try to answer your question if you want to improve the documentation.

[kytta]

I am sorry about how much time it took me to finally get to this. Sometimes I can't achieve the desired study/work/life balance 😅

---

Alright, I have been thinking, and I have so far come up with the following outline. First-level ToC entries are bold, my comments are italicized.

• Homepage - here a small except from README about the project
• Getting started - I suggest uniting Installation (without dev docs) and Usage into one "quick start"-esque page.
  • Installation
  • Usage in Python scripts
  • Usage in Django apps
  • Usage as a command line tool
    • Advanced CLI usage
• User Guide — here the main usage guide; more advanced than the previous chapter
  • PDF vs. HTML
  • Defining Page Layout
    • Managing multiple Page Templates
  • Working with Frames
    • Static Frames
    • Content Frames
    • Control page splits
  • Page Elements
    • Header and Footer
      • Page numbers
    • Table of Contents
      • Change outline levels
    • Tables
    • Images
    • Barcodes
  • Using fonts
    • Pre-installed fonts
    • Custom fonts
    • CJK font support
    • Right-to-Left languages
  • CSS Styling — supported properties
  • Outputting the PDF
• API Reference — purely technical reference
  • HTML API — here the information about supported HTML tags
  • Python API — here the information about Python classes and methods
• Contributing — here some information about working on xhtml2pdf
  • Contributing guide / CoC — there is no separate guide and/or code of conduct; perhaps adding them wouldn't be too bad
  • Development environment
  • Running tests
• Release Notes

---

I would begin by sorting the existing documentation files. Tell me what you think about my structure and how it may be improved 😇

[timobrembeck]

@kytta This outline looks great! Are you still motivated to improve the documentation a bit? Would be much appreciated! 💪

[kytta]

@kytta This outline looks great! Are you still motivated to improve the documentation a bit? Would be much appreciated! 💪

Hi and sorry for not having been active here for a while now; I no longer work at the place where I've used this package, yet I am still very much interested in making its documentation better!