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

[Angel E. <ang...@gm...>]

On Sun, Feb 16, 2014 at 6:29 PM, Jan Decaluwe <ja...@ja...> wrote:
> 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.

For what is worth, I agree with Chris.

My first thought upon seeing the new web page was:

"This looks nice and modern"

quickly followed by:

"This looks quite empty".

Personally whenever I go to a new web page, I like to be able to
understand what it is about by reading what is shown to me on the
landing page. I think a lot of people feel the same. Currently I just
see the "tag line" which is nice, but I don't really see how MyHDL
helps me go "From Python to Silicon".

What is the point of the landing page if I _must_ go to some other
page to see what the whole thing is about?

>> 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.

What Markdown variant are you using? I am partial to pandoc's variant
(http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html)
which I think is very nice.

Cheers,

Angel