Hi Matthew, On Sat Feb 28 2015 at 4:37:57 Matthew Woehlke < [email protected]> wrote:
> I have some documentation for a certain project. I am currently using > sphinx to generate HTML from the marked up documentation, as it seems > like a good fit; reST is a flexible markup format, sphinx lets me link > across documents, and it's very easy to add custom processing (for > example, I've tweaked it¹ into doing inter-document resolution of > `links`_), custom roles, etc. > > Now I have a problem. One chunk of the documentation has been written in > reST. Another (very large) chunk cannot feasibly be written in reST, but > is written in a project-specific format. I can generate the > documentation from the reST files just fine, but I am stuck trying to > figure out how to also process the non-reST files. > > It's my understanding that this should be possible with a custom class > to translate the input file into a docutils node tree. I'm not *too* > worried about that (from writing custom directives / roles, I feel like > I have a reasonable idea how to build a node tree, and I'm similarly not > too worried about the lexical processing of the file itself... at least > I'm not (currently) asking for help with any of that). What I can't > figure out however is how to tell sphinx about this class, and how to > get it to process the files. > > Can anyone shed some light on this? (Bonus points for a complete example > that causes sphinx to also process all *.txt files by turning each line > of the file into a text node.) > For now, sphinx is hard-wired to reST format. Current implementation doesn't have any reasonable API to tell sphinx another file format parser. There is a related ticket https://github.com/sphinx-doc/sphinx/issues/825 that contains a possibility for Markdown or other format capability gist link: https://gist.github.com/tk0miya/31b553b4bd4bf987731e > (¹ Not just for the convenience, either; in some places, I *really* want > to use inter-documentation links in field names, which allow `links`_ > but not :roles:``.) > It depends to docutils syntax. This is not a convenient workaround: :|foo|: bar .. |foo| replace:: :ref:`some-label` > -- > Matthew > Regards, -- Takayuki SHIMIZUKAWA http://about.me/shimizukawa -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
