Comments (11)
@markashleybell Thanks again for the reproduceable spike. I finally dedicated some time to figuring out what's going on here, and I think you nailed it with
actually in their settings they are doing the same thing I've done, i.e. adding an extra ../ to the start of the source file
It appears that one of the problems in creating a tool for developers is that they'll happily just go off and hack it if it doesn't work quite right - so all this time I never realized the default paths weren't working as intended out of the box (since I too set custom paths).
More specifically, the way the path is used is in a ReadFiles
module like this:
new ReadFiles(
Config.FromSettings(settings
=> settings.GetList<string>(DocsKeys.SourceFiles).AsEnumerable())));
And the ReadFiles
module is rooted at the input
folder, so the intent is definitely not to pull in source files from inside the input
folder, that would lead to all kinds of silliness. I think we need to crawl up one for src
folders alongside the input
folder (I.e. in the same project/folder structure) and then also up another for src
folders alongside the Statiq project as in your spike. I'm going to go ahead and make that change now and it'll go out with the next release.
from statiq.docs.
Also I've had no luck adding files from other locations using AddProjectFiles
or AddSourceFiles
... I'm completely confused. It would be nice if there was a way to add a project file explicitly, rather than with a glob so that it could error out when the file is missing.
from statiq.docs.
Same here I'm afraid. I've followed exactly the same path as @rhys-vdw describes above, but no matter what I do, no code is ever processed by the pipeline.
I'm always seeing the Starting Code Input phase execution... (0 input document(s)
messaging when I run it, and no output:
I've tried using the conventional relative src
paths (both at the level above the docs
folder and also within it), and also all of the methods described here to explicitly add code; I've tried those with both relative and absolute paths specified.
It feels like I'm doing something silly, but I can't figure out what that might be, or find any extra clues in the documentation.
Here's the very minimal example repo I've been testing against, in case it either helps, or allows someone to point out my mistake(s):
https://github.com/markashleybell/statiqdocsspike
from statiq.docs.
Ah! Some luck! I think the issue is because the default glob pattern doesn't quite match up with the folder conventions in the docs?
There are obviously some other issues with e.g. absolute paths not working, but adding an extra ../
to the start of the default glob pattern resulted in my pipeline successfully finding the sources:
See here: markashleybell/statiqdocsspike@2243460
from statiq.docs.
I ended up moving to DocFX so I have no more insight into this.
from statiq.docs.
Sorry for the long delay here folks, I've had a number of personal reasons why this project has had to take a backseat for me for a bit but hopefully moving past that soon.
@rhys-vdw Hopefully DocFx is working well for you - it's a good project.
@markashleybell Thanks a lot for exploring this issue a bit more. I still need to dig deeper - there are plenty of folks using Statiq Docs out of the box without problems so I'd like to understand where the differences lie. I suspect, as you did, that there might be some inconsistencies with the Statiq guides and the explanations of where to place files.
from statiq.docs.
@daveaglick You're welcome, and thank you for all your hard work on this project—I do understand how much effort is involved in something like this, and it's very much appreciated.
Whenever you have some time, do you have a few examples of projects where this is working out of the box please?
I've tried a search on GitHub for Statiq.Docs
usage, but the results are a bit overwhelming to comb through... I did find this project, but actually in their settings they are doing the same thing I've done, i.e. adding an extra ../
to the start of the source file. And it seems like all of the others I can initially find are also explicitly passing in paths.
Given a couple of comparisons, I'm happy to try and figure out what I'm doing wrong/differently which is causing my problems, and maybe put in a PR with some tweaks/additions to the docs?
from statiq.docs.
@markashleybell I stumbled across this issue:
You're missing the Docable theme in the ./docs/theme
folder. See Docable#installation on options how to add it.
from statiq.docs.
@nils-a Thanks, but unless I'm missing something—which is certainly possible!—I don't think that would be the cause of this particular issue.
The problem is that the generator wasn't finding my C# source files in order to generate API documentation for them—nothing to do with theming, as far as I can see.
It might well have confused me later though, so thank you for pointing it out!
from statiq.docs.
@markashleybell Ah. Maybe I misinterpreted, then.
I thought that you still had the problem of not seeing the generated api-doc.
from statiq.docs.
@daveaglick That's great, glad you were able to get to the bottom of it!
from statiq.docs.
Related Issues (20)
- Make sure to escape all non-path chars in symbol names for docs
- Deconflict output files for symbols differing only by case in docs
- Docs Recipe - no setting for includeProtected (AnalyzeCSharp.WherePublic)
- Nested types cause URL conflicts for Docs recipe HOT 1
- Docs search breaks on digits
- Material theme for docs HOT 2
- Add xrefs for all API symbols
- Support for Markdown format
- Verify doc comments specification HOT 1
- Feature Request: support XML <include> tags
- GetTypeLink fails for tuples HOT 6
- Add support for automatically linking symbols
- Add support for langword
- Add the props file from Statiq.Web to Statiq.Docs HOT 2
- AddAssemblyFiles to populate "API"?
- Xrefs for API symbols should not contain whitespace
- Methods from base class not listed if base class is generic
- Example on Statiq.Docs output HOT 1
- File Casing issue when deploying to GH-Pages HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from statiq.docs.