Page MenuHomePhabricator

Improve documentation on readthedocs
Open, Requires assessmentPublic

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

Difficulty level
Unknown (require assessment)
Version
-
Why the issue appeared?
Will be filled on close

Event Timeline

runar created this task.Jun 19 2019, 7:18 PM
runar created this object in space S1 VyOS Public.
runar renamed this task from Improve documentation on to Improve documentation on readthedocs.
rob added subscribers: syncer, rob.Jun 30 2019, 8:39 PM

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.

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

rob added a comment.Jul 1 2019, 7:37 PM

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.

pasik added a subscriber: pasik.Jul 2 2019, 3:26 PM