User discussion for the docutils project.

David Sankel | 10 Feb 2012 20:12

Command line definitions

Hello Everyone,

I am attempting to create some rst documentation that is highly modularized. One repository will often pull in rst files from another repository, but the locations of these repositories relative to each-other is going to change based on how someone sets up their computer.

The way I'd usually set this up is with a local-config.mk Makefile with something like:

OTHERREPO_PATH = blah

PYTHONSCRIPTS_PATH = C:/Python27/Scripts/

And then the Makefile will have:

include local-config.mk

all: build/thisrepo.html

build/%.html : src/%.rst

python $(PYTHONSCRIPTS_PATH)/rst2html.py -DOTHERREPO_PATH=$(OTHERREPO_PATH) $< $ <at>

With src/thisrepo.rst having something like:

.. include:: $OTHERREPO_PATH/src/otherthing.rst

I put the mechanism I wish was there in bold font. Is there a canonical way to do what I'm looking for? Perhaps there is a way to add different path's to the <include> style?

Thanks in advance,

David

--
David Sankel
Sankel Software
www.sankelsoftware.com
585 617 4748 (Office)

------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing 
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/

------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing 
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/

headers

David Goodger | 10 Feb 2012 20:23

Re: Command line definitions

On Fri, Feb 10, 2012 at 14:12, David Sankel <camior <at> gmail.com> wrote:
> Hello Everyone,
>
> I am attempting to create some rst documentation that is highly modularized.
> One repository will often pull in rst files from another repository, but the
> locations of these repositories relative to each-other is going to change
> based on how someone sets up their computer.
>
> The way I'd usually set this up is with a local-config.mk Makefile with
> something like:
>
> OTHERREPO_PATH = blah
> PYTHONSCRIPTS_PATH = C:/Python27/Scripts/
>
>
> And then the Makefile will have:
>
> include local-config.mk
>
> all: build/thisrepo.html
>
> build/%.html : src/%.rst
> python $(PYTHONSCRIPTS_PATH)/rst2html.py -DOTHERREPO_PATH=$(OTHERREPO_PATH)
> $< $ <at> 
>
> With src/thisrepo.rst having something like:
>
> .. include:: $OTHERREPO_PATH/src/otherthing.rst
>
>
> I put the mechanism I wish was there in bold font. Is there a canonical way
> to do what I'm looking for? Perhaps there is a way to add different path's
> to the <include> style?

Docutils doesn't have a mechanism for such variable interpolation.
Perhaps Sphinx does?

I suggest using a templating system as a pre-processor.

--

-- 
David Goodger <http://python.net/~goodger>

------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing 
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/
_______________________________________________
Docutils-users mailing list
Docutils-users <at> lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.

headers

David Sankel | 13 Feb 2012 18:14

Re: Command line definitions

On Fri, Feb 10, 2012 at 12:23 PM, David Goodger <goodger <at> python.org> wrote:

On Fri, Feb 10, 2012 at 14:12, David Sankel <camior <at> gmail.com> wrote:
> Hello Everyone,
>
> I am attempting to create some rst documentation that is highly modularized.
> One repository will often pull in rst files from another repository, but the
> locations of these repositories relative to each-other is going to change
> based on how someone sets up their computer.
>
> The way I'd usually set this up is with a local-config.mk Makefile with
> something like:
>
> OTHERREPO_PATH = blah
> PYTHONSCRIPTS_PATH = C:/Python27/Scripts/
>
>
> And then the Makefile will have:
>
> include local-config.mk
>
> all: build/thisrepo.html
>
> build/%.html : src/%.rst
> python $(PYTHONSCRIPTS_PATH)/rst2html.py -DOTHERREPO_PATH=$(OTHERREPO_PATH)
> $< $ <at>
>
> With src/thisrepo.rst having something like:
>
> .. include:: $OTHERREPO_PATH/src/otherthing.rst
>
>
> I put the mechanism I wish was there in bold font. Is there a canonical way
> to do what I'm looking for? Perhaps there is a way to add different path's
> to the <include> style?

Docutils doesn't have a mechanism for such variable interpolation.
Perhaps Sphinx does?

I suggest using a templating system as a pre-processor.

Actually what I ended up doing is use another level of indirection on the include directive, essentially generating a rst file that just includes another one. This worked well and has the benefit of not requiring the addition of another tool to the toolchain.

build/%.rst :

echo .. include:: ../$< > $ <at>

build/%.html : src/%.rst build/otherrepo.rst

python $(PYTHONSCRIPTS_PATH)/rst2html.py $< $ <at>

build/otherrepo.rst : $(OTHERREPO)/thing.rst

With src/thisrepo.rst having something like:

.. include:: ../build/otherrepo.rst

Thanks,

David
--
David Sankel
Sankel Software
www.sankelsoftware.com
585 617 4748 (Office)

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2

------------------------------------------------------------------------------
Try before you buy = See our experts in action!
The most comprehensive online learning library for Microsoft developers
is just $99.99! Visual Studio, SharePoint, SQL - plus HTML5, CSS3, MVC3,
Metro Style Apps, more. Free future releases when you subscribe now!
http://p.sf.net/sfu/learndevnow-dev2