Hi all, Just wanted to chime in about the DocFx work and what DocFx supports and what we could/should use it for (the work in progress PR is here: https://github.com/apache/lucenenet/pull/206)
There are 2 primary functions of DocFx: Generating API documentation for .NET libraries as a static html site and using markdown files as static generated documentation site. DocFx is built in a way that both of these things can exist side by side. That said, it doesn't mean they should be especially based on the previous comments, requirements, wishes in this thread. DocFx has a templating engine and could very well probably support any sort of theme you'd want but there doesn't currently seem to be any public templates showcased apart from the default. The template modifications I've made with the current DocFx PR is just a few color/icon changes but not layout (though it is possible). If you are interested, this is the docs for the templating system: http://dotnet.github.io/docfx/tutorial/intro_template.html . More importantly though, that site that you see there is the static generated documentation site which is build from markdown files and represents what the default theme mostly looks like. If you click on the "API Documentation" menu item at the top, you'll see the generated docs based on the .NET APIs which look quite similar. I think the API docs generated from DocFx is pretty nice and there are extensibility points within DocFx to do some things that have been requested such as extending the Markdown engine to parse custom strings. Example, in the source there is @lucene.experimental in the API docs and I've already created a custom parser to turn this into a custom Note block (similar to this: https://github.com/dotnet/docfx/issues/1737#issue-234133266 ). I'm pretty sure we can achieve all of the requirements/questions asked regarding the API docs with DocFx including incorporating the custom documentation from the Java Lucene repo (see comment here: https://github.com/apache/lucenenet/pull/206#issuecomment-301757155) along with namespace documentation, etc... However, for the regular documentation, if you want an easy to use custom site generator that already has some nice theme templates that can be adjusted than it's probably a better idea to go down that route. Otherwise I think it will take a lot of time to create a fully customized DocFx theme that you are happy with for the custom markdown docs. Another benefit of not using DocFx for the custom docs is that to re-generate the DocFx site takes a long time because it generates both the API docs and the normal docs in the same build and there's a ton of APIs so this process isn't exactly fast. This would end up with having 2 different site builds: One for custom written documentation/wiki/etc... and another for API documentation including code samples and converted docs from the Java Lucene repo. They will of course look differently but I can match any colors, fonts, etc... in the API docs to match the regular docs and since they will be both static file generated sites they can be hosted side by side in different folders. Cheers, Shannon On Mon, Jul 10, 2017 at 8:37 PM George Kinsman <geo...@georgekinsman.com> wrote: > I’m with you on tooling – by the sounds of things this workflow would fit > right in with what already exists – I think the only thing we’d be adding > is a static site generator. Speaking of which, I took a look at the current > static gen ecosystem and it actually looks like Hugo (https://gohugo.io/) > might be a better bet – many more pre-existing themes to adapt, much better > documentation, wider use. I created a demo install in about 10 minutes that > just exported to a dist directory that we could FTP or whatever to the > host. TeamCity setup will be super simple as it’s basically `& hugo -s > $source -d $dist`. > > > > It looks like our experiences with github pages seem to match :-). A link > could be put somewhere (perhaps even per page in generated docs that link > back to file in repo for ease of editing like the ‘suggest edit’ > links you see around) that leads to the branch with the site in it where > people can submit PR’s. They might even be able to be auto-tagged as > documentation. > > > > I tend to agree with you about posting updates – I think most projects > these days keep a blog, or just use twitter for release announcements and > rely on community blogging. > > > > I’ll have a stab at adapting some of the ideas from the JIRA thread to > Hugo and see how I go. > > > > Cheers, > > George > > ________________________________ > From: Shad Storhaug <s...@shadstorhaug.com> > Sent: 08 July 2017 17:37 > To: dev@lucenenet.apache.org > Subject: RE: New Website > > A concern is the amount of maintenance involved with so many tools. We > already have a lot of them, so it would probably be best to reuse the tools > we have if possible to keep the learning curve and maintenance of the > infrastructure down. > > > . I'm not sure how strict the rules are on exactly *what* code needs to > be hosted at Apache, but perhaps it might be wise to create a github org > for Lucene.Net for non-core repositories. We could then store the static > site there, and deploy it to apache.org as per the rules. > > The lucenenet project is already part of the Apache GitHub org. I don't > think it is possible to be part of more than one organization. > > I have worked with GitHub pages before and they recommended to set it up > as a different branch in the same repo. I thought it was a PITA at the time > because I had to do a git clean every time I switched between branches, but > now that I think about the workflow a bit more there could just be separate > working directories for the lucenenet project and the web site each > pointing to a different branch. So, reusing the current repo (on a separate > branch) is a possibility. We could also receive PRs for the doc updates, > provided we provide the instructions where to find them in the repo. And > using a different branch means we can easily have 2 different CI triggers > so they can be independent. > > > > If we used something like Wyam, content updates would become a matter of > changing/adding a new markdown document to the site repository, which could > then be built and deployed using AppVeyor<https://www.appveyor.com/> to > apache.org. > AppVeyor - Continuous Integration and Deployment service ...< > https://www.appveyor.com/> > www.appveyor.com > #1 Continuous Delivery service for Windows Your new build server in a > cloud. Start in minutes. Enjoy faster results. > > > > > No issue with using Wyam. However, we already are using TeamCity for CI > and should probably just create a separate build for the web site on > TeamCity ( > https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds), > so we don't have yet another tool to learn/provide permissions for. We are > also using Powershell for the build script, so it would be best to use > Powershell in this case as well as a wrapper around whatever tooling needs > to run (if necessary). > > > Let me know your thoughts on what I've outlined above - I'm going to > begin working on some ideas for design, which I'll update you with as I go. > I'd be happy to set all of the above up, I think it comes down to where > you'd be willing to host the static site repository, and whether you want > to go down the GitHub org path - assuming you're happy with the direction. > > It sounds like you have the right idea. Actually, I like Autofac's design > even more than SimpleInjector. > > Although, it would be nice if some of the rest of the team let us know > their thoughts as well. Prescott, Stefan, Itamar, Wyatt? > > Does anyone know who has or how to get access to update the existing web > site, or if it is possible to change the DNS record for > lucenenet.apache.org to a new location? The API docs are hosted on the > same subdomain so this applies to that project as well. > > > Recent News/Updates > > Frankly, this is another thing that we really should cut out of the design > unless someone is willing to commit to keeping it updated. If we have a > design that doesn't have any dates or versions on it, it will always be > current and we don't run the risk of it looking dead even if nobody touches > it for a couple of years. I don't see any dates or version numbers on > Autofac or SimpleInjector's websites. Do we really need to announce to the > world that the project teeters on the edge of extinction because not enough > people contribute? It doesn't sound like the right formula to building a > successful community. > > > Vote > > It looks like the last release had a couple of design proposals and the > team voted on the one they preferred ( > http://apache.markmail.org/message/aafm74wp556dlohm?q=lucenenet+website). > Sounds like a great way to have community involvement...but if there is > only time for one design proposal I will vote on it :). > > > > -----Original Message----- > From: George Kinsman [mailto:geo...@georgekinsman.com] > Sent: Saturday, July 8, 2017 9:48 AM > To: dev@lucenenet.apache.org > Subject: Re: Mailing List Documentation > > SimpleInjector's site looks really good, although as you say it's > important to have some code samples on the homepage too. Some examples of > project homepages that I think do a really good job at this include Serilog< > https://serilog.net/>, Autofac<https://autofac.org/> and Nancy< > http://nancyfx.org/>. Each of them have clean designs, code samples, and > installation directions - and each of them are great examples of very > active .NET open source projects too. I think we could implement a nice > modern design with these things front and centre, which would give the > project a great web presence. > > > Where > > Each of those projects are hosted using Github Pages< > https://pages.github.com/>, which is a static content host. They use > static generator tools like Jekyll to convert markdown from a git > repository into a plain html website. If we used something a little more > modern like Wyam<https://wyam.io/> with a custom theme, then we could > just host it in a github repo. Another thing about those previously > mentioned projects is that they each<https://github.com/autofac> have< > https://github.com/serilog/serilog> their own<https://github.com/NancyFx> > GitHub org, with many separate repositories for tooling/examples/public > site etc. I'm not sure how strict the rules are on exactly *what* code > needs to be hosted at Apache, but perhaps it might be wise to create a > github org for Lucene.Net for non-core repositories. We could then store > the static site there, and deploy it to apache.org as per the rules. > > > How > > If we used something like Wyam, content updates would become a matter of > changing/adding a new markdown document to the site repository, which could > then be built and deployed using AppVeyor<https://www.appveyor.com/> to > apache.org. That would give us a very low barrier to entry for > contributions (a GitHub PR), and allow you guys to interact with the > community really easily. The process from an approved PR to the site being > updated would be entirely automatic. The DocFX work could be hosted in a > separate repo too, which could be hosted/deployed alongside the main site. > > > I completely sympathise with you that the project needs to appear to be a > bit more active - I think this would be a great step to take to let the > wider .NET community know about the enormous amount of effort you're > putting into this new port, and to pull in new contributors. I'd love to > help get there however I can. > > > Let me know your thoughts on what I've outlined above - I'm going to begin > working on some ideas for design, which I'll update you with as I go. I'd > be happy to set all of the above up, I think it comes down to where you'd > be willing to host the static site repository, and whether you want to go > down the GitHub org path - assuming you're happy with the direction. > > > Cheers, > > George > > > ________________________________ > From: Shad Storhaug <s...@shadstorhaug.com> > Sent: 07 July 2017 23:32 > To: dev@lucenenet.apache.org > Subject: RE: Mailing List Documentation > > George, > > I started a new issue on JIRA to track the progress of this: > https://issues.apache.org/jira/browse/LUCENENET-589. > > The only thing that is clear about the project at this point is that we > don't really have a clear idea what is required, so the first step is to > start picking brains about what we are actually building. I would say we > could probably have that conversation here on the dev mailing list and use > the information gathered here to list and prioritize requirements on JIRA, > and then work exclusively on JIRA from there. Some of those things to nail > down are where to build it (in the lucenenet repo or somewhere else) where > to host it, and how to deploy it. > > One concern is the ability to easily update it with recent news. I don't > know offhand whether it makes more sense to integrate/build some kind of > simple CMS or if that means we need to build a TeamCity task to deploy it > frequently with updates, or some other method. > > Personally, my primary concern is to keep the project going. It is not > acceptable to have a web site that looks like it belongs to a project that > nobody is maintaining (when in fact we are). We should aim to make it look > like a community that people are not afraid to jump in and help with. I am > partial to SimpleInjector's design: https://simpleinjector.org/index.html > with a modern look and feel, responsive design, and links to all of the > appropriate places to get support for the product and how to get involved. > A quick start guide for Lucene.Net is also essential to learning the basics > before diving into the API docs. > Simple Injector<https://simpleinjector.org/index.html> > simpleinjector.org > Simple injector is free. Simple Injector is open source and published > under the permissive MIT license. Simple injector is, and always will be, > free. > > > > > Thanks, > Shad Storhaug (NightOwl888) > > > > -----Original Message----- > From: George Kinsman [mailto:geo...@georgekinsman.com] > Sent: Friday, July 7, 2017 1:20 PM > To: dev@lucenenet.apache.org > Subject: Re: Mailing List Documentation > > Thanks Shad, great list there. I'd be happy to work on a new public > site/design/icon this weekend - would this be the appropriate forum to post > ideas/progress, or perhaps a github issue/new repo? The DocFX docs look > great too, it'd be great to host them alongside/inside a new site. > > > Also as an aside (perhaps not the right thread for this), but I'm > interested in porting the TermFrequencyAttribute (patch here > https://issues.apache.org/jira/browse/LUCENE-7854) from Lucene 7 in order > to customise the method of obtaining the term frequency at index time. It > looks like the building blocks for this already exist in Lucene.Net 4.8, so > I might try and spend a little time spiking out the idea if there are no > objections. > > > > ________________________________ > From: Shad Storhaug <s...@shadstorhaug.com> > Sent: 07 July 2017 14:56 > To: geo...@georgekinsman.com > Cc: dev@lucenenet.apache.org > Subject: RE: Mailing List Documentation > > > I'd be willing to help out with this in whatever form. Since this > project is an Apache one, does that preclude it from using something other > than apache hosted docs? Something a little more user friendly like ReadMe > (ReadMe.io) or ReadTheDocs might be useful? (ReadTheDocs.io). Both have > free open source licenses/allowances - a great example of readme is here: > https://docs.getseq.net/docs. > > > George, there is a (not so exhaustive) list of ideas of things to work on > here ( > https://github.com/apache/lucenenet/blob/master/CONTRIBUTING.md#other-ways-to-help). > Also see the 2 sections above for additional things that can be done to > help. > > > > -----Original Message----- > From: Prescott Nasser [mailto:geobmx...@hotmail.com] > Sent: Friday, July 7, 2017 11:26 AM > To: dev@lucenenet.apache.org > Subject: RE: Mailing List Documentation > > That's a good question - it's been a while. Stefan do you recall the rules > around this? > > I also am unfamiliar with those services, but would they support the > effort underway for DocFX? I think DocFX outputs some nice HTML which > should be pretty easy for us to host at apache > > -----Original Message----- > From: George Kinsman [mailto:geo...@georgekinsman.com] > Sent: Thursday, July 6, 2017 5:04 PM > To: dev@lucenenet.apache.org > Subject: RE: Mailing List Documentation > > I'd be willing to help out with this in whatever form. Since this project > is an Apache one, does that preclude it from using something other than > apache hosted docs? Something a little more user friendly like ReadMe > (ReadMe.io) or ReadTheDocs might be useful? (ReadTheDocs.io). Both have > free open source licenses/allowances - a great example of readme is here: > https://docs.getseq.net/docs. > > Cheers, > George > > > From: Prescott Nasser > Sent: Friday, July 7, 06:45 > Subject: RE: Mailing List Documentation > To: dev@lucenenet.apache.org > > > Since that was a while ago, I don't think it made it anywhere. Also not > sure there is a benefit to digging through the mailing list again - let's > just make this a re-ask for help? Or open up a new thread with a better > subject to catch some attention? -----Original Message----- From: Shad > Storhaug [mailto:s...@shadstorhaug.com] Sent: Thursday, July 6, 2017 1:41 > PM To: dev@lucenenet.apache.org Subject: RE: Mailing List Documentation I > have to dig through the email, but as I recall we had 2 volunteers offer > their help to build our web site. At the time I assumed that they were > being contacted offline or on a list that I didn't have access to. Do you > know if they were replied to? Perhaps they still have the time and > willingness to help...? -----Original Message----- From: Prescott Nasser > [mailto:geobmx...@hotmail.com] Sent: Friday, July 7, 2017 3:35 AM To: > dev@lucenenet.apache.org Subject: RE: Mailing List Documentation I > couldn't for the life of me remember (or find out) how to get you > permissions. So I filed a ticket with INFRA ( > https://issues.apache.org/jira/servicedesk/agent/INFRA/issue/INFRA-14530). > Definitely need to update all of our documentation and website. I'm not a > web designer - but I can help any community member who is and who wants to > help us revamp our web presence? I'm following the progress on this PR > https://github.com/apache/lucenenet/pull/206, which I think will solve > our documentation issues. Just need to get a lot of people writing up > samples on how to get started using Lucene and different features > -----Original Message----- From: Shad Storhaug [mailto: > s...@shadstorhaug.com] Sent: Thursday, July 6, 2017 1:13 PM To: > dev@lucenenet.apache.org Subject: Mailing List Documentation Hello, We > received a complaint ( > https://github.com/synhershko/LuceneNetDemo/issues/3#issuecomment-307391518) > from someone who wanted to contribute, but couldn't figure out how to sign > up for the dev list because (apparently) the WIKI documentation isn't clear > enough ( > https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists). He > tried to signup using the *actual* email listed on the page ( > list-subscr...@lucenenet.apache.org) and it bounced. He also made mention > of our out of date documentation on the web site and WIKI pages. What > happened with the web site revamp project and can we get that going now > that we are officially on NuGet? People get the impression the project is > dead. Also, could someone give me access to the WIKI so I can start working > on updating the docs there? Is that the recommended place to add > documentation (such as walkthroughs, .NET platform specific setup > instructions, etc.) or should we aim to make that part of the API > documentation (https://github.com/apache/lucenenet/pull/206)? While we > are on that subject, is the plan to put the new API docs at > http://incubator.apache.org/lucene.net/docs/3.0.3/Index.html (with the > new version number), or somewhere else? Thanks, Shad Storhaug (NightOwl888) > -- *Shannon Deminick*CTO [image: Umbraco] <http://umbraco.com> *Umbraco A/S * Haubergvej 1 DK-5000 Odense C Denmark http://umbraco.com <http://umbraco.com> Phone +45 70 26 11 62 <+4570261162>
