Consistent file naming for search optimization¶

Problem description¶

Now that the migration to RST has settled down, we can see that using the former xml:id for file names meant that some RST file names use underbar (_) as space indicators and some RST file names use hyphen (-) as space indicators.

Our conventions are to use hyphens for all RST files so that the resulting built HTML files are human-readable and search-engine-readable.

Proposed change¶

Update all files in the openstack-manuals repository, a guide at a time, to match our convention of using hyphens for RST file names.

Change any RST file names using underscore to use hyphen instead. Do not change file names if they use hyphens for spacing.

Change any folder names using underscore if and only if the folder results in output on a URL that contains an underscore.

Do not change image or figure file names.

Change any hyperlinks that refer to underscore-named files.

Redirect any old file names to new file names on the web server itself in the www/static/.htaccess file.

Implementation¶

Dependencies¶

Coordination of efforts and landing patches.

Testing¶

Test changed file names for no broken links resulting.

Test redirects.

References¶

Contributor guide: http://docs.openstack.org/contributor-guide/docs-structure.html#file-naming-conventions

To get the list of Work Items I ran this type of search:

ls ~/src/openstack-manuals/doc/user-guide/source/ | grep _