Opened 9 years ago

Closed 3 years ago

#10299 closed defect (fixed)

errors during Sphinx "make html" process

Reported by: Marcus Reimann Owned by: Kitson Kelly
Priority: high Milestone: 1.11
Component: Documentation Version: 1.4.0b
Keywords: 14open Cc:
Blocked By: Blocking:

Description

There are some errors during the "make html" process with Sphinx. This errors lead to missing links (and pages) within the Dojo docs which are delivered with each new release.

Example: Within the page dojo/index.html there should be a link to the djConfig-page, but the current make process isn't able to find this link and as a consequent doesn't link to this page. The result is, that the whole page for djConfig (with important informations about djConfig) is missed in the exported HTML files.

The problem seems to be the handling of the relative/absoulute links within the make process:

If you look at the Wiki page http://docs.dojocampus.org/dojo/index, you'll find the following link:

`djConfig <djConfig>`_

This link works great within the MoinMoin? wiki. After the export from MoinMoin? there is the same link in another form available within the file source/dojo/index.rst:

:doc:`djConfig </djConfig>`

During the make process Sphinx warns, that it's not possible to find the file "djConfig". And with that, Sphinx doesn't link to the page "djConfig" and also don't create the "djConfig.html" file.

It seems, Sphinx is only able to search within the current working directory, but not in the directory above (djConfig is located in source/ and not in source/dojo/).

During my investigation I've also found another problem: There are old and/or wrong files in the directory source/:

  • dijit.rst (The content does not reflect the current state of the Wiki. There is just an "#REDIRECT dijit/index" within this page)
  • dijit-themes.rst (have to be moved to dijit/themes.rst)
  • dojoc.rst (The file is already deleted within the Wiki. However, the file still exists within the source/-directory)
  • dojo.rst (The content does not reflect the current state of the Wiki. There is just an "#REDIRECT dojo/index" within this page)
  • internals.rst (seems to be outdated)
  • manual.rst (The file is already deleted within the Wiki. However, the file still exists within the source/-directory)

Regards,

Marcus

Change History (10)

comment:1 Changed 9 years ago by dante

Owner: set to tklipstien

comment:2 Changed 9 years ago by Adam Peller

Owner: changed from tklipstien to klipstein

comment:3 Changed 9 years ago by Adam Peller

Keywords: 14open added

moving 1.4 open tickets to 1.5

comment:4 Changed 9 years ago by Marcus Reimann

Friendly reminder

comment:5 Changed 9 years ago by bill

Milestone: 1.51.6

1.5 is released, moving remaining tickets to 1.6

comment:6 Changed 9 years ago by dante

Owner: changed from klipstein to dante
Status: newassigned

I've done a lot of work on these. Some seem unavoidable and are simply warnings and things work. the Errors need fixed. I started an etherpad and a room on irc #dojo-doc so we can collaborate on this nearly realtime. The doc process from moin->static is now a series of makefile commands, and the warnings are saved in build/warnings.txt after running make html. More on this as after I actually get a new static deployed with most fixes.

comment:7 Changed 8 years ago by dante

Milestone: 1.61.7

most of the remaining issues come from transformations caused by the wiki -> rst conversion. Once we drop MoinMoin and can edit directly from the .rst files on disk, we can easily identify and eliminate these errors.

Moving to 1.7, which is the timeframe for moin deprecation. (the rstwiki solution will suffice for user contributed documentation, allowing for advanced contribution directly via vc).

comment:8 Changed 7 years ago by bill

Owner: changed from dante to Kitson Kelly

Not sure if this is still an issue.

comment:9 Changed 7 years ago by Colin Snover

Milestone: 1.82.0

1.8 has been tagged; moving all outstanding tickets to next major release milestone.

comment:10 Changed 3 years ago by dylan

Milestone: 2.01.11
Resolution: fixed
Status: assignedclosed

We've fixed as much as we are going to fix with this workflow.

Note: See TracTickets for help on using tickets.