Re: [myhdl-list] myhdl.org website migration

[Jan D. <ja...@ja...>]

On 02/14/2014 02:47 PM, Christopher Felton wrote:

> Couple (minor) comments on the new site.
>
> Is there a way to easily link back to the site from
> the manual?  I found it a little frustrating jumping
> to the manual and back to the site.

The manual link is to the manual generated with readthedocs.org,
which looks like a convenient automatic method for the future.

Anyone knows how include return links in readthedocs
manuals?

> I realize the menu system has the links to get started,
> etc.  But I think having some more content on the landing
> page would be beneficial for new visitors, etc.  I can
> create a pull-request with some ideas.

I suggest to discuss this first. I want to learn from
good examples (bootstrap) and keep the landing page
as "to the point" and short as possible.

Now we have the name and a tagline. I see the value
of adding a one or two liner description, and perhaps
the latest "News" item.

> Also, my contribution plan to the new site is adding
> examples.  In the past I experimented with adding the
> examples to the manual and using doctest to verify the
> examples when a new version of the manual was created.
> I think this would be good as release tests (that is
> verifying the examples on the site still work).  Now,
> that the new website is in a repository, I propose we
> add a little (as little as possible) formality to the
> examples so we can leverage this code collection for
> release testing, e.g. all examples should have:
>
>       1. description write up
>       2. .py file with working example
>       3. test for the example
>
> In addition, there are ways to embedded the code from
> bitbucket in the example write-up, the write-up can
> always have the latest code (easy to maintain the examples),
> thoughts?

Mm, I don't think we want to do repo accesses over the
net on every build. Of course, you could add a script
to pull the sources automatically on demand.

The straightforward way would be to have some "include"
facility in the markdown format - however markdown doesn't
support this :-( No doubt we can find a workaround or add
support ourselves, but I propose to delay that for a
future optimization.

-- 
Jan Decaluwe - Resources bvba - http://www.jandecaluwe.com
     Python as a HDL: http://www.myhdl.org
     VHDL development, the modern way: http://www.sigasi.com
     World-class digital design: http://www.easics.com