Delete the old apio documentation

[zapta]

The old apio documentation is not updated and is not maintained. Please delete it (or replace it with a link to the wiki documentation here).

https://apiodoc.readthedocs.io/en/stable/source/installation.html

@Obijuan , @cavearr

[cavearr]

Hi @zapta! i think we need to focus documentation in only one place, or read the docs or github wiki. This is something has been worked by @Obijuan , i think he should define the best place and try that all make the effort in that direction.

[zapta]

Hi @cavearr, I think that @Obijuan moved the documentation to the apio wiki, hence the request to replace the old version with a link to the new one.

See the 'old documentation' link on the right side here

https://github.com/FPGAwars/apio/wiki

[cavearr]

Yep! in my opinion should be only one place but is my opinion, i understand you have automatice some documentation in readthedocs?

[zapta]

Hi @cavearr, I don't remember doing anything for readthedoc.

I am asking to replace it with a link to the wiki doc here.

[cavearr]

Sorry! i don't understand you! i don't have access to the readthedocs apio site. I suppose obijuan has it.

[cavearr]

@zapta in my point of view the ideal shoud be put a banner at the top of readthedocs site that advertise about this is an old documentation and linking with the wiki and in some time remove it and redirect to the wiki.

[zapta]

@cavearr, that's a good idea, can you do that? I never accessed apio's readthedoc.

Also, any idea how to update the wiki doc for the next release, before it's being released, without modifying the public doc of the current apio prod version?

[cavearr]

@zapta i'm trying to find how to access to readthedocs, give me the weekend please ;)

About the wiki this is the thing that i don't like github wiki, because you have only one for all branchs.

The only way that i view if we need to maintain both is creating a folder in dev branch (for example "wiki" name) and copy all the wiki and update it. We could put a link in the wiki ,referer as "Development wiki" the navigation not be the same because github not display indexes, etc, bug uses could navigate and read for the docs, when release, we could copy in the Actions the wiki folder to the wiki project.

I'm thinking in real time ando not mediatte much ,what do you think?

[zapta]

How about having a second repo for dev doc and then copy from one to the other when we release? We can also have cross links between them, prod doc and dev dec. Or, we can go back to readthedoc. It's more aesthetic IMO and supports versioning and controlled release. In addition, the doc is in the same repo as the code such that changes can be submitted together.

…

On Sat, Dec 14, 2024 at 3:01 PM Carlos Venegas Arrabé < ***@***.***> wrote: @zapta <https://github.com/zapta> i'm trying to find how to access to readthedocs, give me the weekend please ;) About the wiki this is the thing that i don't like github wiki, because you have only one for all branchs. The only way that i view if we need to maintain both is creating a folder in dev branch (for example "wiki" name) and copy all the wiki and update it. We could put a link in the wiki ,referer as "Development wiki" the navigation not be the same because github not display indexes, etc, bug uses could navigate and read for the docs, when release, we could copy in the Actions the wiki folder to the wiki project. I'm thinking in real time ando not mediatte much ,what do you think? — Reply to this email directly, view it on GitHub <#498 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAQVMQMRS4WPVF6XDC6GSPD2FS2GBAVCNFSM6AAAAABTTZSGW6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNBTGM3DSMRSGE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[cavearr]

@zapta , do you know docusaurus? i use in other projects and is great, more powerful than readthedocs and i think the migration from github wiki will be very ease. We could create a page under fpgawars domain like apio.fpgawars.com where this documents deploy under github pages, what do you think ?

[zapta]

Hi @cavearr, a few questions about docusaurus,

1. Can we use the apio repo to store also the content of the docusaurus docs? (having the same process, permissions, and tools for code and docs makes its easier. readthedoc supports it).

2. Can we have at the same time two doc versions that are published? (I think readthedocs supports it, need to confirm)

3. What kind of web servers serve the docuasaurus docs? Does docusaurus provides public servers, do we need to create and manage our own?

4. Do we need to install software tools to use docusaurus? I saw some references to node js.

Personally I prefer simple and main stream solution that don't have a steep learning curve for new contributors.

[cavearr]

@zapta docusaurus is similar to readthedocs, we would run it on github pages .

In the repository there would only be markdown files, perfect for monitoring and editing. In fact, the current wiki or readthedocs could possibly be migratable almost automatically or with some minimal change.

In actions, the flow will be configured with docusaurus, it will be installed, the repo documentation folder will be deployed and the static site will be generated that will be uploaded to github pages associated with the domain that I have proposed or another (it could be apio.github.io this is whatever you prefer, my point of view is to start using the fpgawars domains which I think brings much more seriousness to the project, but this is my vision), they could be maintained both readthedocs as docusaurus but I think it is crazy to maintain both versions, if I get access, which I think I will, I would put the banner directing the users or the wiki or the new docusaurus.

We could initially migrate the wiki and update it to the new apio commands, put the banner in readthedocs and add a banner to the new doc.

With docusaurus we could have a main page that is simply a presentation of the project and some links to the documentation of the different branches and the github repository.

We could have the documentation displayed for example in https://apio.fpgawars.com/docs/v0.1/ and https://apio.fpgawars.com/docs/v0.9/ .... that is, we could have all the documentations of any branch and even versioned (documentations from different versions, even previous ones, could coexist). I can take care of all this if you think it's a good idea (To get everything going, pages, initial design, etc).

[zapta]

@cavearr, if you want, go ahead and set it up. At minimum, please try to demonstrate the following

1. Two different URLs, for prod and for dev versions, both coexist at the same time.
2. Two directories in apio-repo, e.g. doc/prod and doc/dev which contains the markdown content of the docs.
3. The two pages get updated automatically once the markdown in their respective repo dir is modified.

[cavearr]

@zapta Wouldn't it make more sense to just have a doc/ directory and have it versioned by development branch or tag? so that the branch and the corresponding git tag would be reflected in the urls, do you think?

I am now very focused on closing the integration in Icestudio, I have found some problems that are taking me more work, in fact I am cutting features that I wanted to take advantage of to add to have the functional version as soon as possible and in the coming weeks I will improve the refactoring. But I can prepare this in a few days, count on it.

[Obijuan]

Sorry to interrupt this thread. I do not like readthedocs. I do not like docusaurus either. Please, keep the documentation in the wiki. I've been using the wiki for many years with my studends with great success. I always write all the manuals, technical notes, documentations and so on using the wiki
If you want to test something new, ok, do it. But I will continue writting the documentation of the stable apio version in the wiki. Once the apio development is released, the wiki will be updated.

It is ok for me to delete the old apio documentation. Readthedocs was used initially, but it was migrated to the wiki many years ago. The main problem is not the infraestructure. It is to have the time to write it, and then to keep it updated. I have to spend a lot of time doing it

[cavearr]

Ok! don't worry, we maintain only the wiki page, and we could update when release the new version and maintain only the wiki at github, i prefer only use the wiki.

I'll try to put the banner in readthedocs to redirect to the wiki and in some time delete it. I think is important focus all effort in only one place.

Thanks @Obijuan @zapta

[zapta]

I am not sure I follow, but please let me know when I can update the doc for the dev version and where.

…

On Sun, Dec 15, 2024 at 12:15 PM Carlos Venegas Arrabé < ***@***.***> wrote: Ok! don't worry, we maintain only the wiki page, and we could update when release the new version and maintain only the wiki at github, i prefer only use the wiki. I'll try to put the banner in readthedocs to redirect to the wiki and in some time delete it. I think is important focus all effort in only one place. Thanks @Obijuan <https://github.com/Obijuan> @zapta <https://github.com/zapta> — Reply to this email directly, view it on GitHub <#498 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAQVMQNIOOARW4MDL6YQB5L2FXPOPAVCNFSM6AAAAABTTZSGW6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNBUGAZTSNBYGM> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[Obijuan]

It will be located in the wiki. I will ask you for help when we freze apio as a preparation for the upcoming release

[zapta]

@Obijuan, I have time now to update the documentation while I am waiting on this #453

I have a pending commit for deleting the deprecated commands and prefer not to make other code changes to avoid merge.

[Obijuan]

ok. The oficial wiki is: https://github.com/FPGAwars/apio/wiki
Add or change whatever you want. Maybe you can create pages for the new commands, and add them in the side bar
This week i am extremelly busy, so my answer will be very delayed

[zapta]

@Obijuan, no worries, whenever you are available.

I tried to work with the version control of the github wiki but it's very tricky. I was to create a local repo using github clone https://github.com/FPGAwars/apio.wiki.git and made changes but couldn't submit them nor was I able to fork the accompanying wiki repo of apio.

My vote is to go back to readthedoc. The docs use the same repository and pull requests processes as the code and we can release a new version together with the python code. Must simpler for maintaining the docs in sync with the code.