-
Notifications
You must be signed in to change notification settings - Fork 638
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[DRAFT] Partial docfx fix - Missing some plugins #958
Conversation
Thanks for this! I'm going to merge this into an issue branch in this repo for collaboration. I was seemingly able to fix the toc locking by setting maxParallelism to 1. Obviously not ideal for performance, but reliability > performance right now, and it's still not too slow. |
I have merged this with my work into this issue branch: https://github.com/apache/lucenenet/tree/issue/911 We can now use this branch to finish up collaboration on this issue. Note though that I am getting an error building your plugins changes, not sure why. However, it's great that running with |
This is great. That would explain why I saw it choke when the 3rd part JSON parser tried to read the ToC. As for the version numbers, we ended up resorting to using Powershell to update them here: lucenenet/websites/apidocs/docs.ps1 Lines 182 to 192 in 0d7bba7
|
I think we should be able to do that with plugins now as a post-processor! IIUC, anyways. |
I was able to fix the plugin build error by excluding some files that were using the old docfx SDK. I went ahead and excluded the rest of those files that were commented out, no reason in keeping them in the csproj. By the time we merge this we should remove those from source control (they will of course always be available in prior version history if needed). I'm testing this now and will review the rest of the plugin code to see what all is needed to be implemented. This is very exciting to use the latest docfx! |
I added a post-processor for the https://github.com/apache/lucenenet/tree/issue/911 Next up, I'll look into seeing if the things we were doing in PowerShell can be done in a post-processor instead, since we have much more control over the output now. |
Hmm...the whole thing is in Powershell, except for the DocFx bit :). I suggest you have a look at the Docs and Website Documentation and the build automation for the docs and the website. They are set up to build the docs and then submit a PR to the lucenenet-site repo (although, the trigger isn't working and it requires starting manually). Also, if you checkout the tag for beta00016, you should be able to run the build prior to the DLL conflict to see it work. Ideally, the UX and procedure won't have to change for the upgrade. |
Sorry, I was meaning replacing the "HACKs" you were referring to here: #958 (comment) We at least should be able to do that for the CLI index. I'll look into it. |
The CLI docs version replacement was an easy change, made that use Next up I'll be looking into why the header links aren't working, but once that is working we should be in good shape for the API docs site. |
This is a leg more on the fix @paulirwin have been trying out for solving #911
This is based on the commits @paulirwin made here: https://github.com/paulirwin/lucene.net/tree/issue/911
Use this to finish off the what is left to have docfx fully working.
What did I add?
toc.yml
As mentioned here there was a problem with the
toc.yml
being locked this was fixed by changing the path to"./toc.yml"
instead oftoc.yml"
.While the first fix solved the problem I noticed in one case when running locally that the file got locked anyway therefore I added a 1 second delay between starting new site out builds and haven't seen the error since.
js
andcss
)When starting the docs site locally the pages weren't showing the CSS or using the js files because the route was wrong due to the missing
_rel
variable, therefore, I've added a slash/
before all uses of these files so it works locally and removed the ending slash from thedocfx.global.subsite.json
.docfx.vendor.css
was also changed todocfx.vendor
.min.css.
docfx.vendor.jswas also changed to
docfx.vendor.min.js`I'm not sure if it works in all cases that it should but I've created a
EnvironmentVariableProcessor
that makes sure to replaceEnvVar:ENVIRONMENT_VARIABLE
to the actual value of the environment variable. As far as I could tell this is only used on the index page but I have no idea if this is correct. I haven't replaced the other plugin modules in these changes so that is still missing.Next step
@paulirwin or @Shazwazza feel free to take these changes and finish them off 😄
I think the only thing missing is the remaining commented out plugin files otherwise it looks to be working.
How I've been testing
I've used the following command to test it.