I looked into this some more last night and wanted to post an update with another manual way to assign Help API links to specific locations in a document.
The HTMLHelp TOC file .hhc lists the reference location for each item in the HTMLHelp TOC. This is a more concise list of entry points for the Help API than the index file I proposed in my last post. Here's an example: If your document propertyfuncs.txt has a sub-section with the text: References ========== Then a TOC item will be created with the name: propertyfuncs.html#references. You can assign a Help API ID by appending the following to the .hhp file built by Sphinx: [ALIAS] IDH_PROP_REFS=propertyfuncs.html#references [MAP] #define IDH_PROP_REFS 1010 On the subject of adding the functionality to Sphinx using an extension, it seems the best way would be to have a new directive so the Help ID and Alias can be specified in the source files. The source files seem to be the best place to define this information. This directly ties the source and API data so you don't have to remember to edit the API alias when the section text or file name changes. I intend to make an effort at building such an extension but it's not my day job. In the meantime, I'm still just adding code to the make.bat file to append hard-coded alias and ID data to the end of the .hhp file. Dave Parker On Aug 2, 10:42 am, David <parke...@gmail.com> wrote: > Use the index directive to specify locations in the documentation you > would like to access with the Help API. The index directive should be > placed directly before the point you want to access. Sphinx will use > these directives to build an HTMLHelp index file (.hhk). Links will > look like this: > propertyfuncs.html#index-6, where index-6 is a specific location in > the file propertyfuncs.html. If you want to use the Help API to point > to this location add the following to your .hhp file generated by > Sphinx: > > [ALIAS] > IDH_Air_rho=propertyfuncs.html#index-6 > > [MAP] > #define IDH_Air_rho 1050 > > I started out manually pasting the Alias and ContextID's to the end of > the Sphinx generated .hhp file. More recently, I've modified my > make.bat batch file to append the Alias and Context ID's to the .hhp > file each time the HTMLHelp builder is called. > > I'm interested in developing a Sphinx extension to auto-generate the > Alias and Context ID's from the Sphinx index. Of course a typical > index contains far more entries than needed for the Help API, but I > figure I'll use the entries I need and ignore the rest. I started > looking at the Extension API docs this weekend and I think I see two > options for the extension: > 1. Use the build-finished event to trigger a function to generate the > Context ID's and Alias's and append them to the .hhp file. This should > work if the objects Sphinx uses to build the index can still be > accessed. > 2. Create a new builder that subclasses the current HTMLHelpBuilder. I > don't like this option it seems like too much work. > > Either option will have to avoid replacing previously generated > Context ID's to prevent breaking downstream code that utilizes the > ID's. > > I'm just a Sphinx user and Python hacker though so I would appreciate > any advice and guidance from the experienced Sphinx developers. > > Thanks, > David Parker > > On Jun 12, 9:35 am, Troy <blueb...@gmail.com> wrote: > > > Is this even possible. I would like to switch from asciidoc/docbook > > format to sphinx. I just need this one bit of information to > > accomplish that task. > > > On Apr 21, 9:09 am, Troy <blueb...@gmail.com> wrote: > > > > I am currently using Asciidoc to generate my documentation and it > > > works well except on windows I have to use cygwin to get things > > > running. It is ok for me but a complex setup for others that want to > > > use this system. So I am look at alternatives and Sphinx is one of > > > them because of thehtmlhelpoutput. > > > > Looking through the documentation I am unable to find information on > > > how to specify 'map ids' which are used by the api to access specific > > > sections of a help file through code. For example if I specify amapid=400 > > > in my code it will open the help file to the specific > > > section. The closest thing that I could find in the documentation is > > > 'Cross-referencing arbitrary locations'. In thehtmlhelpoutput folder > > > should be two files an alias.h and context.h > > > > The context.h contains: > > > > #define mvb_about 801 > > > #define mvb_establish_reference_line 802 > > > #define mvb_stope_limits 803 > > > > The alias.h contains: > > > mvb_about=iRing Help.htmlhelp/index.html#_about > > > mvb_establish_reference_line=iRing Help.htmlhelp/ar01s02.html > > > mvb_stope_limits=iRing Help.htmlhelp/ar01s04.html > > > > Any ideas on how to accomplish this would be greatly appreciated. > > > Cheers, > > > Troy > > > > -- > > > You received this message because you are subscribed to the Google Groups > > > "sphinx-dev" group. > > > To post to this group, send email to sphinx-...@googlegroups.com. > > > To unsubscribe from this group, send email to > > > sphinx-dev+unsubscr...@googlegroups.com. > > > For more options, visit this group > > > athttp://groups.google.com/group/sphinx-dev?hl=en. > > -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
