Page MenuHomeVyOS Platform

Improve documentation on readthedocs
Closed, ResolvedPublic

Description

Following the resent discussions about phasing out the wiki in favor to readthedocs i've started work to improve the documentation in readthedocs and migrate parts of the wiki that needs to be moved.

This ticket is created as a reference to this work, until a PR is available it will be held under: https://github.com/runborg/vyos-documentation

comments/improvements are welcome

Details

Version
-
Is it a breaking change?
Unspecified (possibly destroys the router)

Event Timeline

runar renamed this task from Improve documentation on to Improve documentation on readthedocs.
runar created this object in space S1 VyOS Public.

Hi,

for some weeks/months i began to migrate the first wiki articles to github.
@syncer wanted to redirect the old wiki pages to the new rtd pages, so i create a list to document the progress.

https://docs.google.com/spreadsheets/d/1KMWciLcHuqHlfBQelCHlYfs06fwhQ1LV5uYcTnPpKhw/edit#gid=0

Some links to the rdt pages are outdated now, because the pages where reordered or renamed.
I decided not to adopt outdated content, but we can discuss it.

runar added a subscriber: Unknown Object (User).Jun 30 2019, 9:45 PM

Hi rob! Nize that more people is involved in this :) i've started the large task of marking things that have been migrated to github, it's a lot of pages with outdated info thats not going to be migrated, also i find a lot of pages not having enough "end user" documentation that i don't know where to put.. eg. devel docs etc..

What i've done so far is to add a header to pages that are migrated over to readthedocs with info about the migration and a link to the new page, this is done using this template: https://wiki.vyos.net/wiki/Template:Migrated , to add the template to a page use this at the top of a page: {{Migrated | url = https://vyos.readthe....... }} the url field is the link to the new url
This also adds the page to a category named Migrated pages (https://wiki.vyos.net/wiki/Category:Migrated_pages) that list all pages where this header is present.

I've also created a category for pages that is not supposed to be migrated for some reason: https://wiki.vyos.net/wiki/Category:Don%27t_migrate
To add pages to the Don't migrate category add this at the bottom of the page: [[Category: Don't migrate]]

To get a hold of the progress i've created an simple python script to create a list of pages that needs attention (not marked as migrated or don't migrate.. to list all remaining pages:

#!/usr/bin/env python3
import urllib.request
from lxml import etree
import re

def get_url(url,xpath):
    with urllib.request.urlopen(url) as fp:
        mystr = fp.read().decode("utf8")
    root = etree.fromstring(mystr)
    return root.xpath(xpath)

allpages =    set([x.text for x in get_url("http://wiki.vyos.net/wiki/Special:AllPages", '//ul[@class="mw-allpages-chunk"]/li/a[not(@class="mw-redirect")]')])
dontmigrate = set([x.text for x in get_url("https://wiki.vyos.net/wiki/Category:Don%27t_migrate", '//div[@id="mw-pages"]/div/div/div/ul/li/a')])
migrated =    set([x.text for x in get_url("https://wiki.vyos.net/wiki/Category:Migrated_pages", '//div[@id="mw-pages"]/div/div/div/ul/li/a')])

pages_to_migrate = [x for x in set(allpages-dontmigrate)-migrated if not re.search("\([cC]ommand\)", x or "")]
print("Pages to Migrate:")
for a in pages_to_migrate:
    print(" * ",format(a))

print("Pages total: {}".format(len(pages_to_migrate)))

this script fetches all pages from the wiki and removed the those present in migrated and don't migrate.
It also removed all pages containing (command) because we need to make them from scratch at the new place (not in the form they currently have)

i've done this work with @Unicron.

As for what you say about redirects, i don't think that's so smart to do, it's better to mark the old url's with the new url and let the user know that he is in the wrong place.
it might be that the notification box should be even larger than the one i've created.. :)

Hi,

nice, a banner in the wiki page is also an elegant way to document the progress.
I would go through all pages i have already migrated and add the new via your template.

about the command pages i made a little test to generate the whole commandtree from the new xml interface definition files. Even if not all are defined in the new style yet. see here:
https://github.com/rebortg/vyos-docubuilder
The gen_interface_structurev2.py file generate the *.rst files in the docs/source folder. It is just a concept.

Unknown Object (User) subscribed.Sep 9 2019, 5:11 PM
dmbaturin set Is it a breaking change? to Unspecified (possibly destroys the router).
dmbaturin claimed this task.
dmbaturin subscribed.

Now the readthedocs process is well-established.