Update Apio documentation

[zapta]

This issue is for updating the apio documentation wiki.

Instead of editing the wiki in-place I created an empty wiki structure at the temporary repo https://github.com/zapta/apio-wiki-dev/wiki and will fill it in with existing and new content. Once we are happy with the content, we will replace it in the official apio wiki.

Goals

• Useful, informative and easy to follow
• Easy path for new Apio users
• Concise. Include only necessary information rather than a 'kitchen sink' approach.
• Easy to maintain.

[zapta]

@Obijuan, @cavearr, I transffered writing the new documentation to this issue (the other one is for the deletion of the readthedocs).

1. My current goal is to have complete and updated documentation of apio 1.x.x in the official apio github wiki.

2. I use a temporary repo for the draft https://github.com/zapta/apio-wiki-dev/wiki and once it will be ready we will copy to the official apio site.

3. Down the road I suggest to revisit the idea of using a more polished tool for the apio reference material while using the wiki for quick and informal complementary content that students and others can easily write. Wiki is very convenient for quick authoring and brainstorming but it's rendering format, readability, and user experience leave much to be desired.

[cavearr]

@zapta check if you want this:

https://eleventy-libdoc.netlify.app/

i'm trying it for some things and i thik could be very interesting.

[zapta]

@cavearr, check also https://www.mkdocs.org, it's compatible with github markdown, can generate with a looks and feels, including readthedoc, and served by github so we don't need a separate account.

Nice to have requirements:

1. Simple source text format, ideally markdown similar to github.
2. Good user experience and professional look.
3. Does not require an additional account (e.g. readthedocs)
4. Source files can be versions in a docs directory in the github apio repo
5. Published automatically when we check in to the apio repo.
6. Apio contributors can easily make changes without having to learn the docs system too much.

[cavearr]

each of this options are good for me

[zapta]

One useful feature will be tabbed code blocks that allows to give parallel command samples for linux, mac, and windows. Currently I use only Mac bash examples in the Wiki I am writing.

Same for parallel per-platform installation instructions. With the Wiki it's just one long list which most of it is not relevant to the user.

[zapta]

@Obijuan, @cavearr, the first pass of the new Apio docs is ready in the link below (except for the apio and package release instructions which need more work and workflows changes). Please verify them for completeness and correctness and post here any suggestions or comment you may have.

https://github.com/zapta/apio-wiki-dev/wiki

[cavearr]

I need to view in deep but impressive @zapta , this is awesome! take me some tome to review, but the first view is incredible.

[Obijuan]

Nice doc! Great job! Thanks a lot

[zapta]

I am also experimenting with a mkDocs. .md pages are exact copy from the wiki https://github.com/zapta/apio-wiki-dev/tree/main/docs and a simple 'publish' command publishes them as a github Pages site, below with the 'material' theme which is popular but there are others, including read the docs look alike.

Sample page https://zapta.github.io/apio-wiki-dev/standalone-installation/

[zapta]

I am going now page by page in the mkDocs collection and cleaning them. It will be in a good shape once I will be done.

https://zapta.github.io/apio-wiki-dev/

[cavearr]

sounds very good, as i'm telling you i'm experimenting with similar platforms for icestudio, what are the advantages of mkdocs in front of others?

[zapta]

I can't compare to others since I didn't tried them, I just asked ChatGPT what is the common and mainstream system to use. It's well done, very easy to use, integrates well with github and doesn't require an external account, it publishes to github Pages.

Format is controlled by a central .css each time I want to make a style change ChatGPT gives me another snippet to add to the .css.

https://github.com/zapta/apio-wiki-dev/blob/main/docs/stylesheets/extra.css

[cavearr]

thanks @zapta , i'll try it, the ideal is apio and icestudio could use the same documentation system.

Thanks again!

[zapta]

@cavearr, I completed the doc cleanup. Please take a look https://zapta.github.io/apio-wiki-dev/

Next step is to submit it to Apio and publish on its Pages site (I can create an auto publish workflow.

Can you enable the github Pages FPGAwars/apio? This is how mine looks like.

[zapta]

@Obijuan, @cavearr, please enable Pages on the FPGAwars/apio repo. The default setting in the screenshot above worked for me on my temp doc repo.

[cavearr]

Over what branch you want to manage github pages for Apio?

[zapta]

I am using the defaults and it works.

See the screenshot I posted here earlier, it's called gh-pages and then there is something '/(root)' which by the icon it looks like a directory.

[zapta]

@cavearr, if you will decide to use a docs system other than mkDocs, it shouldn't be too difficult to migrate the content from mkDocs since the markfown is simple. However, mkDocs is slick, simple, and very easy to use.

[cavearr]

Hi @zapta we don't have this branch, i think you create it in some moment. We need to select between master or develop:

[zapta]

Hi @cavearr, chatgpt says that mkDocs creates it. Please try this in the apio repository.

pip install mkdocs

mkdocs gh-deploy --force

[zapta]

I think the branch gh-deploy is for the files that mkdocs compiles from the markup pages when we pubish.

[cavearr]

i'll try it and tell you

[cavearr]

Hi @zapta i'm try it in develop branch of apio:

pip install mkdocs

This commands results ok

but when i ran :

mkdocs gh-deploy --force

I obtain this error:

Error: Config file 'mkdocs.yml' does not exist.

i don't know if i need to do something before or running the command in some directory.

[zapta]

Ok thanks @cavearr, let me send first the mkdocs file. It includes a publishing workflow that may do it automatically.

[zapta]

@Obijuan, @cavearr,

The new Apio doc is now stable, checked in, and published at https://fgpawars.github.io/apio

Is the other content that we want to move to it from old Wiki documentation https://github.com/fpgawars/apio/wiki before we deprecate it?

After clearing the old wiki, it can be used for quick and informal sharing of Apio related ideas and information that is not curated and maintained as strictly as the official docs.

BTW, the new documentation is made of simple markdown files under the docs dir that are published automatically when changed and checked in. https://github.com/FPGAwars/apio/tree/develop/docs

[cavearr]

Hi @zapta, @Obijuan should review the documentation and work with you to manage the relationship, deletion, or any other issues related to the wiki page. @Obijuan maintains the wiki and has invested a lot of work into it, and I don't know if it's included in the new documentation or if @Obijuan is comfortable enough with it to delete the wiki. I don't know if @Obijuan doesn't like the new system or isn't comfortable with it, whether they could coexist.

Please discuss this.

[Obijuan]

Hi @zapta ! Great work! I think it is time to release apio 1.0.0. As I am using it for my lectures, I need to test it deeply. I will finish soon the final exams of this semester and I hope i will have more free time to test it and release it I will try to open an issue as soon as possible with the steps to go for releasing apio 1.0.0

Please, stay tuned! (Thanks a lot for all your hard work)

[zapta]

Hi @Obijuan, that's a very good plan.

We have here a placeholder for the release process https://fpgawars.github.io/apio/creating-apio-version/ it we can complete it after this release.

The source of that page is at docs/creating-apio-version.md. If you edit in your local repo, you can preview the mkdocs rendering with mkdocs serve https://zapta.github.io/apio/updating-the-docs/#previewing-local-changes

Meanwhile, I will work on removing the old commands documetations from the wiki to avoid confusion..

[zapta]

@Obijuan, I updated a few fields in pyproject.toml but couldn't test them so most likely you will need to tweak when you will release.

https://github.com/zapta/apio/commit/b2094ac7ae38f3dc33244aeced381e2507ec4ac5

[zapta]

@Obijuan, @cavearr, anything else I should move from the wiki to the new documentation? Options in a table instead of pre-text? More detailed examples? Anything else?

https://fpgawars.github.io/apio/cmd-apio-upload/