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

[Christopher F. <chr...@gm...>]

On 2/16/14 11:29 AM, Jan Decaluwe 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.

I haven't fully caught up on this thread yet but I
like the changes/additions.

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

I guess I was thinking a build would not pull from the
web but rather as part of the release process you run
all the tests in the site-myhdl/examples (a repo you
have locally).

My thought, is that maybe we structure the examples
directory in the repo so that -possibly- it can be used
as a collection of test code.  From my perspective this
allows us to leverage a code base and a process to evaluate
quality of examples.  My thought is the example directory
would be organized as:

     site-myhdl/examples/
        example1/
            example1.md      # the write-up
            example1.py      # the full example in a python
            test_example1.py # a test for the example

If we encourage a structure like this we can simply test all
the examples.  And it would be neat to automatically give each
example a "badge" for each version of myhdl - but that is
neither here nor there.

This isn't something that has to happens right away but if
we set the precedence that an example needs a working .py
and a test then the rest can be added as time permits.

Regards,
Chris