search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.48k stars 2.11k forks source link

Feature request: Single text file builder #2750

Open ghost opened 8 years ago

ghost commented 8 years ago

This request is to add a new builder ('singletext' ?) to build a single plain text file from rst sources. Similar to singlehtml where everything is in one file. My use case is this: To batch run aspell on a single file, get a list of suspect words. I'll manually search for them across my rst file set. An added feature would be to insert a comment showing the path to the rst source for a text segment. This would help tracking down the rst file rather than searching for the word, but there may be a better way (to link the content back to the source).

lehmannro commented 8 years ago

Hmm, what would this builder gain over a cat _build/text/*.txt > single.txt? I guess TOCs might be the only concern here?

ghost commented 8 years ago

1) You'll have to do a recursive find -exec cat ... because I believe the dir under _build/text is a structure matching the sphinx project dir. 2) Does that approach guarantee the order in the single text file is that same as the document structure? I (and other users!) still want the single text file to be a valid output doc, even though my use case is just for spelling. But you're right, I haven't spent much time seeing what I can do for myself without a dedicated builder. I'll have a look/think.

StFS commented 6 years ago

I'm looking for something similar. Did you find anything useful @paulanthonyjacobs ?

ghost commented 6 years ago

I ended up using singlehtml and aspell mode sgml plus various other skip tokens (script, code, abbr...), and a .aspell.pws full of acceptable words to get something working. We suffer the cost of an extra build just for spell-checking - plain text would still be better.

ghost commented 6 years ago

Still very much looking forward to this after having discovered antiques GNU 'diction' and 'style' that help automate readability metrics. Meanwhile, using w3m -dump -T text/html to convert the singlehtml output into text suitable for passing through the previously mentioned utilities.

mabraham commented 6 years ago

I would also find "singletext" useful for constructing e.g. a plain text install guide or release notes from structured .rst (intended primary for HTML output) so that they can be placed in the top-level of a source code tarball.