Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Documentation #12

Open
62 of 84 tasks
ili opened this issue Apr 2, 2017 · 18 comments
Open
62 of 84 tasks

Documentation #12

ili opened this issue Apr 2, 2017 · 18 comments
Assignees
@sdanyliv @ili @MaceWindu

Comments

@ili
Copy link
Contributor

ili commented Apr 2, 2017 •
edited by FabioNascimento
Loading

Ok, let's speak about our Achilles' heel - documentation.
To be honest everything is awful, only documentation is start page & a little bit of wiki. We should work on it!
My suggestion is to build documentation using DocFX, things to be done:

  • Write XML documentation
  • Examine DocFX & prepare contributors' guide
  • Configure CI to build documentation on each commit
  • Find out how & where documentation can be hosted

Volunteer needed.

XML documentation tasks

If you are going to document any section please write comment below an we'll mark that it is in process:

  • LinqToDB.Data.DataConnection : .ctor region

  • LinqToDB.Data.DataConnection : public properties region

  • LinqToDB.Data.DataConnection : configuration region

  • LinqToDB.Data.DataConnection : connection region

  • LinqToDB.Data.DataConnection : command region

  • LinqToDB.Data.DataConnection : transaction region

  • LinqToDB.Data.DataConnection : MappingSchema region

  • LinqToDB.Data.DataConnection : GetTable methods

  • LinqToDB.Data.DataConnectionExtensions : SetCommand region

  • LinqToDB.Data.DataConnectionExtensions : Query* regions

  • LinqToDB.Data.DataConnectionExtensions : Execute* regions

  • LinqToDB.Data.DataConnectionExtensions : BulkCopy region

  • LinqToDB.Data.DataConnectionExtensions : Merge region (@MaceWindu)

  • LinqToDB.IDataContext

  • LinqToDB.DataExtensions: Table Helpers region

  • LinqToDB.DataExtensions: Insert region

  • LinqToDB.DataExtensions: InsertOrReplace region

  • LinqToDB.DataExtensions: InsertWithIdentity region

  • LinqToDB.DataExtensions: Update region

  • LinqToDB.DataExtensions: Delete region

  • LinqToDB.DataExtensions: DDL Operations region

  • LinqToDB.LinqExtensions: Table Helpers region

  • LinqToDB.LinqExtensions: LoadWith region

  • LinqToDB.LinqExtensions: Scalar Select region

  • LinqToDB.LinqExtensions: Delete region

  • LinqToDB.LinqExtensions: Update region

  • LinqToDB.LinqExtensions: Insert region

  • LinqToDB.LinqExtensions: InsertOrUpdate region

  • LinqToDB.LinqExtensions: DDL Operations region

  • LinqToDB.LinqExtensions: Take/Skip/ElementAt region

  • LinqToDB.LinqExtensions: Having region

  • LinqToDB.LinqExtensions: IOrderedQueryable region

  • LinqToDB.Common.Configuration

  • BulkCopy: LinqToDB.Data.BulkCopyType, LinqToDB.Data.BulkCopyOptions

  • LinqToDB.ExpressionMethodAttribute

  • LinqToDB.Sql.TableFunctionAttribute

  • LinqToDB.Sql.TableExpressionAttribute

  • LinqToDB.Sql.PropertyAttribute

  • LinqToDB.Sql.GroupBy

  • LinqToDB.Sql.FunctionAttribute

  • LinqToDB.Sql.ExpressionAttribute

  • LinqToDB.Sql.EnumAttribute

  • LinqToDB.Sql math functions region

  • LinqToDB.Sql string, text, guid and binary functions regions

  • LinqToDB.Sql datetime functions region

  • LinqToDB.Sql convert functions region

  • LinqToDB.Sql common functions region

  • LinqToDB.ServiceModel.SoapDataContext

  • LinqToDB.ServiceModel.ServiceModelDataContext

  • LinqToDB.Mapping.TableAttribute

  • LinqToDB.Mapping.StoredProcedure (sic!)

  • LinqToDB.Mapping.SequenceNameAttribute

  • LinqToDB.Mapping.ScalarTypeAttribute

  • LinqToDB.Mapping.Relationship

  • LinqToDB.Mapping.PrimaryKeyAttribute

  • LinqToDB.Mapping.NullableAttribute

  • LinqToDB.Mapping.NotNullAttribute

  • LinqToDB.Mapping.NotColumnAttribute

  • LinqToDB.Mapping.MapValueAttribute

  • LinqToDB.Mapping.MapValue

  • LinqToDB.Mapping.AssociationAttribute

  • LinqToDB.Mapping.ColumnAliasAttribute

  • LinqToDB.Mapping.ColumnAttribute

  • LinqToDB.Mapping.DataTypeAttribute

  • LinqToDB.Mapping.IdentityAttribute

  • LinqToDB.Mapping.InheritanceMappingAttribute

  • LinqToDB.Mapping.MappingSchema: constructors

  • LinqToDB.Mapping.MappingSchema: ValueToSqlConverter region

  • LinqToDB.Mapping.MappingSchema: Default Values region

  • LinqToDB.Mapping.MappingSchema: CanBeNull region

  • LinqToDB.Mapping.MappingSchema: Convert region

  • LinqToDB.Mapping.MappingSchema: DefaultMappingSchema region

  • LinqToDB.Mapping.MappingSchema: Scalar Types region

  • LinqToDB.Mapping.EntityDescriptor

  • LinqToDB.Mapping.ColumnDescriptor

  • LinqToDB.Mapping.AssociationDescriptor

  • LinqToDB.Mapping.InheritanceMapping

  • LinqToDB.Linq.Expressions: MapMember region

  • LinqToDB.Linq.Expressions: Sql specific region

  • LinqToDB.Linq.Expressions: Provider specific functions region
@jogibear9988
Copy link
Member

maybe we can look at https://github.com/StefH/System.Linq.Dynamic.Core
i think he hosts doc on azure. or we use github.io

@ili
Copy link
Contributor Author

ili commented Apr 2, 2017

It looks like https://github.com/StefH/System.Linq.Dynamic.Core uses standard xml comments documentation, DocFX uses combined approach xml comments + md files. This looks better for me.

@inickvel
Copy link

inickvel commented Apr 4, 2017 •
edited
Loading

May be readthedocs.io ?
For example, autofac docs

@sdanyliv
Copy link
Member

sdanyliv commented Apr 4, 2017

@inickvel, looks like autofac have generated samples and tutorials by readthedocs, but API documentation by other tool. Maybe it is not ok to have such additional service for API. Seems that DocFx generates both parts of documentation.

@ili
Copy link
Contributor Author

ili commented Apr 5, 2017

@inickvel please correct me if I'm wrong, readthrdocs generate documentation from soma marckup files, so we'll need to write two docs - marckup and xmldoc, copying data from xmldoc to marckup. DocFX helps to avoid this, that's why I'm looking forward to use this engine

@pebezo
Copy link

pebezo commented May 1, 2017

I agree, documentation is the weakest point to what is otherwise an awesome library/tool.

I'm not familiar with DocFX, but, from a little browsing, it looks like the typical auto-generated API reference documentation. While this is nice and definitely needed, folks new to the library need more guidance than a typical API reference provides. Is there a platform that offers (ties in) both?

I could help with the documentation (wrote most of the readme.md on the start page), but I too could use some guidance from those more familiar with the inner workings of the library. Without this, I'm left pecking around the source code and not knowing if I'm missing something cool "hidden" somewhere else in the codebase.

@ili
Copy link
Contributor Author

ili commented May 2, 2017

@pebezo that's cool! You are welcome to ask any questions we'll do our best to help you!

@pebezo
Copy link

pebezo commented May 2, 2017 •
edited
Loading

What would help is having an outline, like a table of contents. Then, for each node a few bullet points about what should be listed. For example: "inserting data" would list "inserting from context class", "inserting with identity", "inserting select fields", "bulk copy", etc. For the more complicated/esoteric todos it would also be helpful to include a link to a test case or a code sample.

Having something like this could serve as the starting point. Then if we have questions about various parts at least we know what to ask.

@MaceWindu
Copy link
Contributor

@pebezo I agree. I was trying to create such table recently with a list of topics that makes sense to document. See this page: https://github.com/MaceWindu/linq2db/wiki

There are two ways - spend a lot of time trying to find a best way to work on documentation, or just start documenting stuff step-by-step. I think we should use second approach. We can always change structure and format of documentation later when we have something to structure and style :)

E.g. each time we receive a question which could be answered by documentation - we should provide a link to documentation.

Let's take this one: linq2db/linq2db#650 - we can create following pages:

  • Sql Extensions (general write up on extensions and extension atributes)
  • Sql Extensions, included into linq2db (here we could document Sql.Like and other methods of Sql)
  • Native methods support (here we could document string.StartWith and other such methods)

I will go through all issues, including closed, later today and will post a list of those that could be used as starting points for documentation.

@sdanyliv
Copy link
Member

sdanyliv commented May 3, 2017

Also @pebezo, @MaceWindu, maybe you can create xml docs for public members of DataConnection class?

@ili
Copy link
Contributor Author

ili commented May 3, 2017

I'm fully agree with @sdanyliv, let's start from writing xml documentation for public API (DataConnection and mapping attributes).

This would be the core for documentation.

@pebezo it would be great if you can start pull requests with xml doc, we'll help with any additional info required

@MaceWindu
Copy link
Contributor

MaceWindu commented May 3, 2017 •
edited by ili
Loading

Below is a list of XML documentation tasks - maybe we should add it to first message? (ili i'v moved them)
Feel free to extend it and reserve tasks for yourself to avoid duplicate work.

For anyone, who will decide to write documentation - inspect code that you plan to document, see what it does and how it used - having misleading documentation is even worse than no documentation.

After a first few contributions I think we will be able to compile initial list of requirements for documentation.
A bit later I will add a list of tasks for wiki-documentation.

@MaceWindu
Copy link
Contributor

MaceWindu commented May 6, 2017 •
edited
Loading

Here I tried to compose a list of tasks for Wiki documentation which I think could be usefull.

First of all regarding existing pages:

  • readme.md : move Let's get started section to wiki and replace it with link to a documentation root page
  • readme.md : add license section with link to license
  • readme.md : update build status section with information about OS/Frameworks used, so people will see where they can use linq2db immediately
  • readme.md : add links to other linq2db projects with short description
  • issue reporting page - I don't think anyone use it. We should create issue template where we can ask user to specify required data and place a link to this page

List of tasks for new wiki pages. Each task contains topic that we should cover and optionally list of issues/PRs that could contain additional information like 'how it works' or some use scenarios or questions from users. Sorry, this is a pretty raw list, but I think we can use it as a starting point for now and it is hard to analyze such a big amount of data quickly.

  • documentation root page - short intro and list of links to other documents / areas
  • linq2db configuration: LinqToDB.Common.Configuration, connection strings, providers. How to use DataConnectionExtensions.ExecuteProc()? #11 #87 #248 #250 #285 #365 #616
  • logging/tracing Fixed typo in function name #37 , [WIP] Documentation update. #41 #118 #331 #500 #646
  • BulkCopy: configuration and use #277 #361 #418
  • Expression methods #225 #463 #650
  • known issues with workarounds - for long standing issues with no ETA #133 #214 #256 #264
  • mapping schema : attributes Wcf service transaction #17, Update BulkCopy docs for asynchronous support #32, #62 #246 #279 #293 #443 #517 #583 #611
  • mapping schema : fluent mapper Small typo in Supported Databases documentation #26 #225 #286 #446 #468 #520 #521 #565 #580
  • mapping schema : converters #70 #96 #267 #279 #324 #339 #507
  • mapping schema : enums mapping #110 #468
  • mapping schema : xml mapping #410
  • native methods, converted to SQL (LinqToDB.Linq.Expressions.LoadMembers() )
  • stored procedures support #57 #81 #151 #168 #187 #188 #323
  • LoadWith #61 #251 #434 #482 #527
  • Full-text search #66
  • Window functions #73 #542
  • Development environment #145 #457
  • F# support #177 #178 #194 #195 #523 #524
  • Providers dependencies #201 #239 #304 #512
  • Sql class #217 #232
  • FAQ / uncategorized #87 #170 #193 #212 #222 #225 #229 #215 #237 #283 #359 #375 #382 #406 #441 #460 #470 #481 #528 #534 #595 #648
  • Benchmarks #309 #325
  • Testing #387
  • IoC #390
  • Optimistic locking #553

@sdanyliv
Copy link
Member

Added Window Functions documentation https://github.com/linq2db/linq2db/wiki/Window-Functions-(Analytic-Functions)

@MaceWindu
Copy link
Contributor

MaceWindu commented May 15, 2017 •
edited
Loading

Looks good!
Could you add a section with links to documentation for supported db engines, not only Oracle:
MSSQL: https://docs.microsoft.com/en-us/sql/t-sql/queries/select-over-clause-transact-sql
Postresql: https://www.postgresql.org/docs/current/static/tutorial-window.html
DB2 z/OS: https://www.ibm.com/support/knowledgecenter/en/SSEPEK_12.0.0/sqlref/src/tpc/db2z_olapspecification.html
DB2 LUW: https://www.ibm.com/support/knowledgecenter/en/SSEPGG_11.1.0/com.ibm.db2.luw.sql.ref.doc/doc/r0023461.html
DB2 iSeries: https://www.ibm.com/support/knowledgecenter/en/ssw_ibm_i_73/sqlp/rbafyolap.htm
Informix: https://www.ibm.com/support/knowledgecenter/en/SSGU8G_12.1.0/com.ibm.sqls.doc/ids_sqs_2584.htm
SAP HANA: http://help-legacy.sap.com/saphelp_hanaplatform/helpdata/en/20/a353327519101495dfd0a87060a0d3/content.htm
SAP ASE: http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.infocenter.dc38151.1602/doc/html/san1278452950084.html
Firebird 3: https://www.firebirdsql.org/file/documentation/release_notes/html/en/3_0/rnfb30-dml-windowfuncs.html

Edit: In your PR you also have links for MariaDB and SqLite (but I don't see window function there)

@sdanyliv
Copy link
Member

Done

@sdanyliv
Copy link
Member

Also there is another documntation generator https://wyam.io/
It is used by cake build for documentation.

@ghost
Copy link

ghost commented Jul 15, 2017

@sdanyliv

colors of wyam.io site == pain

hopefully other things are not bad...

@MaceWindu MaceWindu transferred this issue from linq2db/linq2db May 26, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@sdanyliv sdanyliv

@ili ili

@MaceWindu MaceWindu

Labels
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@jogibear9988 @inickvel @sdanyliv @ili @MaceWindu @pebezo